The dhis-web-birtviewer module is a simple module that allows running reports designed with BIRT Designer inside DHIS 2.

How to install DHIS 2 with the BIRT viewer?

STEP 1: Build the dhis-web-birtviewer

All web modules are built through the parent project dhis-web. Edit dhis-2/dhis-web/pom.xml and make sure the module dhis-web-birtviewer is listed under modules:

<modules>
    <module>dhis-web-maintenance</module>
    <module>dhis-web-dataentry</module>
    <module>dhis-web-commons</module>
    <module>dhis-web-commons-resources</module>
    <module>dhis-web-importexport</module>
    <module>dhis-web-reporttool</module>
    <module>dhis-web-datamart</module>
    <module>dhis-web-validationrule</module>
    <module>dhis-web-dashboard</module>
    <module>dhis-web-birtviewer</module>
  </modules>

Then build the dhis-web project using maven: $mvn clean install

STEP 2: Build the DHIS 2 web portal including the dhis-web-birtviewer module

All web modules are bundled together in the dhis-web-portal project and to use dhis-web-birtviewer you must also add a dependency to the dhis-web-birtviewer project in dhis-2/dhis-web/dhis-web-portal/pom.xml:

<dependency>
    <groupId>org.hisp.dhis</groupId>
    <artifactId>dhis-web-birtviewer</artifactId>
    <version>${version}</version>
    <type>war</type>
</dependency>

Then build the web portal with Maven: $mvn clean package

STEP 3: Add your new dhis.war (the new dhis 2 portal with BIRT viewer) file to your tomcat webapps folder

I've used tomcat in this example, but you can of course use jetty or other servlet containers as well

Stop tomcat
Delete your dhis (named dhis or similar) folder inside webapps/
Copy dhis.war from dhis-2/dhis-web/dhis-web-portal/target/dhis.war to <tomcat folder>/webapps/

STEP 4: Download and install the BIRT runtime application

Download the BIRT runtime application from the BIRT download page
Unzip the downloaded file to any suitable/temporary location
Copy the folder called WebViewerExample and paste it into your tomcat (or similar) webapps folder. Rename the folder to birt-viewer.
Then you must add your jdbc drivers to the birt runtime application by putting your appropriate jar files in the webapps/birt-viewer/WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc\drivers folder. Download driver here: Mysql jdbc drivers and PostgreSQL jdbc driver
NOTE: if you are running java 1.5 and postgres you must use the jdbc3 driver and if you are using java 1.6 the jdbc4 driver.

If running tomcat 6 you need to add the commons logging library to the webapps/birt-viewer/lib folder. or For more instructions on how to install BIRT runtime have a look at the BIRT online documentation

STEP 5: Add a configuration file for the birt viewer

In order for DHIS 2 to run BIRT reports the application must know where the birt-viewer application is running.
These settings are defined in a file called birt.properties that must be located in DHIS2_HOME. The user referred to in DHIS2_HOME is the user running tomcat or similar.

The file must contain the following two properties. birtviewer.home referes to the absolute path to the BIRT webapp directory inside the servlet container. birtviewer.directory refers to the part of the URL coming after the base URL (eg. http://localhost:8080). This will in most situations be equal to the name of the BIRT webapp folder.

birtviewer.home = /home/olati/tools/apache-tomcat-6.0.14/webapps/birt-viewer
birtviewer.directory = birt-viewer

STEP 6: Make sure the database connections in your reports are valid on the machine running the report viewer

If your reports have been designed on another machine then you must make sure that the database connections and queries are also valid on the machine where the report viewer (BIRT runtime) is running. That is also why you had to make available the necessary jdbc drivers to BIRT runtime in a previous step. BIRT needs to find the correct database, tables and columns to work properly. You can modify and/or verify your database connections by opening your reports in BIRT designer and preview them there, or you can simply open the xml-based report design files (.rptdesign) in any text editor and modify there.

STEP 7: Start up DHIS 2 and BIRT runtime

Now that both your new dhis 2 war file and the BIRT runtime war file are located in tomcat/webapps you can start up tomcat again.

How to use the dhis birt viewer module?

STEP 1: Upload your reports designs

Navigate to the dhis-web-birtviewer module from the main menu and from the birt viewer menu select <upload design>

STEP 2: Run the report

From the birt viewer menu select <View report> and select your report design from the drop down list and click on <View report>. The report will open in a separate window. The report might ask for user input depending on whether any report parameters have been defined in the report design. The report can be exported to pdf and excel and be printed and saved.