BIRT Report Module Installation Guide

Owned by Former user (Deleted)
Last updated: Jan 06, 2017 by Hillary Bagiire
5 min read

Compatibility

IMPORTANT:  The BIRT Report Module currently does NOT support BIRT Runtime 2.6.1!

  • BIRT Report Module 2.5.1.x requires BIRT Runtime 2.5.1
  • BIRT Report Module 2.3.2.x requires BIRT Runtime 2.3.2
  • BIRT Report Module 2.3.1.x requires BIRT Runtime 2.3.1

Older versions no longer supported

  • BIRT Report Module 2.1 requires BIRT Runtime 2.3.2
  • BIRT Report Module 2.0 requires BIRT Runtime 2.3.1
  • BIRT Report Module 1.9 requires BIRT Runtime 2.2.2
  • BIRT Report Module 1.8 requires BIRT Runtime 2.2.2
  • BIRT Report Module 1.7 requires BIRT Runtime 2.2.2
  • BIRT Report Module 1.6 requires BIRT Runtime 2.2.2
  • BIRT Report Module 1.5 requires BIRT Runtime 2.2.2
  • BIRT Report Module 1.4 requires BIRT Runtime 2.2.1.1 (can be compiled from source)
  • BIRT Report Module 1.3 requires BIRT Runtime 2.2.1 (can be compiled from source)
  • BIRT Report Module 1.2 requires BIRT Runtime 2.2.0
  • BIRT Report Module 1.1 requires BIRT Runtime 2.2.0 (can be compiled from source)
  • BIRT Report Module 0.6 requires BIRT Runtime 2.2.0
  • BIRT Report Module 0.3 requires BIRT Runtime 2.2.0 (can be compiled from source)
  • BIRT Report Module 0.2 requires BIRT Runtime 2.2.0

Download

IMPORTANT:  The BIRT Report Module currently does NOT support BIRT Runtime 2.6.1, so please download Runtime version that is supported (e.g. 2.5.1, 2.3.2, or 2.3.1).

You likely want to use the following Archived Builds page.

  1. Find the build that you want on the Archived Builds page (either 2.5.1, 2.3.2, 2.3.1)
  2. Dowload BIRT Report Designer
    1. Choose RCP Designer if you are running Windows.
    2. Choose All-in-One if you are running Ubuntu or Mac and don't have Eclipse installed already.
    3. Choose Framework if you have an instance of Eclipse already installed.
  3. Download BIRT Runtime Engine (click Runtime)
  4. Download BIRT Report Module

Installation Instructions

Step 1. Install BIRT Report Designer (optional)

If you plan to design reports locally, you need to install the BIRT Report Designer. 

If you are using Windows, the easiest way to install the

  1. Download the latest version of the BIRT RCP Designer
  2. Extract the BIRT RCP Designer to your local file system (i.e. c:\birt-rcp-designer-x_y_z)

If you are using Ubuntu, the easiest way to install the Report Designer is using the All-in-One download. 

  1. Download the latest version of the BIRT Report Designer
  2. Extract the BIRT Report Designer to your local file system (i.e. /var/lib/birt-report-designer-x_y_z)

If you are using Eclipse, you can download the Framework version, extract it, and copy it into your current eclipse installation (under the plugins directory).

Step 2.  Install BIRT Runtime Engine (required)

If you want to run the BIRT Module on a server, you MUST first install the BIRT Runtime Engine.

  1. Download the latest compatible BIRT Runtime Engine (click Runtime button).
  2. Extract the BIRT Runtime Engine to your local file system (i.e. Windows: c:\birt-runtime-x_y_z; Ubuntu: /var/lib/birt-runtime-x_y_z)
  3. Note the path to the BIRT Runtime Engine (e.g. this is your BIRT home directory - in Windows: c:\birt-runtime-x_y_z\ReportEngine; in Ubuntu: /var/lib/birt-runtime-x_y_z/ReportEngine)

Step 3.  Install MySQL Driver (optional)

If you plan to design reports that use the SQL dataset to make calls to a MySQL database, you will need to install a MySQL driver.  OpenMRS uses a MySQL driver, so you can simply copy that 

To install the MySQL Driver into BIRT Runtime Engine

  1. Download the latest MySQL driver
  2. Copy file to BIRT Runtime Plugin directory
    • For example, PATH_TO_BIRT_RUNTIME\ReportEngine\plugins\org.eclipse.birt.report.data.oda.jdbc_<version>\drivers

To Install MySQL Driver into BIRT Report Designer

  1. Open BIRT Report Designer
  2. Create New Data Source > JDBC Data Source
  3. Manage Drivers ...
  4. Add ...
  5. Locate the appropriate MySQL driver
  6. Click Open
  7. Click Ok

To create a new SQL Data Source in the BIRT Report Designer

  1. Open BIRT Report Designer
  2. Create New Data Source > JDBC Data Source
  3. Enter properties
    • Driver Class: com.mysql.jdbc.Driver (v3.1)
    • Database URL: jdbc:mysql://localhost:3306/openmrs?autoReconnect=true
    • User Name: your db username
    • Password: your db password
  4. Click 'Test Connection ...'
  5. Click 'Finish'

Step 4.  Install BIRT Report Module to OpenMRS

a.  Install BIRT Report Module

  1. Download the latest BIRT Report Module (click the Download button).
  2. Login to OpenMRS as an administrator
  3. Navigate to Administration > Manage Modules
  4. Browse for .omod file that you downloaded
  5. Click the Add Module button

b.  Edit Settings (formerly Global Properties from platform 1.8 downwards)

Assuming you are logged in as an Administrator:

  1. Navigate to Administration > Manage Settings (formerly Global Properties form platform 1.8 downwards)
  2. Enter values for the BIRT  settings (formerly global properties from platform 1.8 downwards)
  3. Click Save at the bottom of the page
  • birt.birtHome
    Specifies the absolute path to the BIRT Report Engine. Must include ReportEngine subdirectory.
    Example: in Windows: c:\birt-runtime-x_y_z\ReportEngine; in Ubuntu: /var/lib/birt-runtime-x_y_z/ReportEngine
  • birt.datasetDir
    Specifies the absolute path to the reports dataset directory (for CSV/XML data sources).
    Example: <user_home>/.OpenMRS/reports/datasets
  • birt.defaultReportDesignFile
    Specifies the name of the default report design file. Not implemented yet.
    Example: default.rptdesign
  • birt.imageDir
    Specifies the absolute path to the image directory where BIRT will find generated charts and graphs. Not implemented yet.
    Example: C:/Documents and Settings/Justin Miranda/Application Data/OpenMRS/reports/output/images
  • birt.loggingDir
    Specifies the absolute path for log files written by BIRT Engine.
    Example: C:/Documents and Settings/Justin Miranda/Application Data/OpenMRS/reports/logs
  • birt.outputDir
    Specifies the absolute path to the report output file when reports are generated.
    Example: C:/Documents and Settings/Justin Miranda/Application Data/OpenMRS/reports/output
  • birt.reportDir
    Specifies the absolute path where report design files are uploaded.
    Example: C:/Documents and Settings/Justin Miranda/Application Data/OpenMRS/reports
  • birt.reportOutputFile
    Specifies the absolute path to the reports output file.
    Example: C:/Documents and Settings/Justin Miranda/Application Data/OpenMRS/reports/output/ReportOutput.pdf
  • birt.reportOutputFormat
    Default output format.
    Example: pdf
  • birt.reportPreviewFile
    Specifies the absolute path to the report preview file.
    Example: C:/Documents and Settings/Justin Miranda/Application Data/OpenMRS/reports/ReportPreview.pdf

c. Start BIRT Report Module

Assuming you are logged in as an Administrator:

  1. Navigate to the Administration > Manage Modules
  2. Click the green arrow next to the BIRT Report Module

Step 5.  Configure Users with Required Privileges

The following privilege may be necessary for various activities.

  • Manage Reports (deprecated, but still used for the time-being)
  • Edit Reports
  • View Reports
  • Delete Reports

Using a Stored Procedures as a Datasource

Dynamic Parameters

When using MySQL stored procs as a datasource, you may want to pass a parameter from the report to the stored proc, to do this, from the Data Explorer Pane, right click:

  • Report Parameters > New Parameter: Create a new report parameter
  • Data Set > Edit > Query: In the definition where you specify the stored proc name and parameters, use static parameter that will give sample results
  • Data Set > Edit > Query: Once BIRT has determined all of the output columns, edit the definition and stick a question mark where you want to have a dynamic parameter
  • Data Set > Edit > Parameters: you'll see the names of the stored proc parameters, just link the parameter to the report parameter you created

Exception "User does not have access to metadata..."

When running a report that uses a database connection and using stored procedures for the data source, the module will run stored procedures under the openmrs_user account. It seems that it even ignores the connection settings specified in BIRT.

As a result, you may find that you get an exception when trying to run the report:
"java.sql.SQLException:User does not have access to metadata required to determine stored procedure parameter types. If rights can not be granted, configure connection with "noAccessToProcedureBodies=true" to have driver generate parameters that represent INOUT strings irregardless of actual parameter types."

  • To get past this error, we must grant the MySQL openmrs_user appropriate permissions
  • First determine the username that OpenMRS uses to connect to MySQL
    • mysql> show processlist;
  • Once you know the user name, as the MySQL root user, perform the grant:
    • mysql> GRANT SELECT ON `mysql`.`proc` TO 'openmrs_user'@'localhost';