Installation

Just execute following from your application directory:

grails install-plugin birt-report

Running an example

An example can be found at http://www.jepemuc.de/download/birt-report-test_0.3.zip (it is just 280kB). This example uses a quartz job to read and cache report descriptions (e.g. to do context or parameter dependent report listing) and provides a simple way to upload report documents and associated files (like images). After unpacking the zip you need to install the plugins by:

grails install-plugin birt-report
grails install-plugin quartz

grails upgrade

Using the plugin

Generating Reports

To generate a report as PDF you need to do the following

def downloadAs = {
        String reportName = params.remove('id')
        String reportExt = 'pdf'
        params.remove('action')
        params.remove('controller')
        params.remove('name')
        def options = birtReportService.getRenderOption(request, 'pdf')
        def result=birtReportService.runAndRender(reportName, params, options)
        response.setHeader("Content-disposition", "attachment; filename=" +reportName + "."+reportExt);
        response.contentType = 'application/pdf'
        response.outputStream << result.toByteArray()
        return false
    }

Localization of reports

The localization of BIRT reports is described at the BIRT help and the BIRT FAQ; a tutorial can be found at Dummies Mind. Once the report and its property-files are deployed the report should be rendered using the locale provided by grails (based on the accept-language header of the request). This locale can be overwritten by appending the url parameter lang (see the Grails userguide).

This mechanism works well if you have a request. If the service is used without a request (e.g. in a quartz job) it falls back to the locale of the host system which might not be what is needed. Therefore the run, render, and runAndRender methods offer the possibility to overwrite the locale by providing a java.util.Locale object as an optional parameter. This way the locale used in the report can be specified explicitly.

BirtReportService interface

The following methods are provided wich require the following parameters:

• listReports : returns a list of the available reports found in the reportHome directory
• getReportProperties : returns the standard and custom properties of a specific report
• reportName - name of the report (without extension)
• userProps - list of user properties to be read from the report
• getReportParams : returns a complete list of the report parameters
• reportName - name of the report (without extension)
• getReportParamNames : returns a list of the report parameter names
• reportName - name of the report (without extension)
• getRenderOption : creates a render option which can be used with runAndRender or render
• format - format of the output to be generated (html, pdf, xls, doc, ppt)
• getRenderOption : creates a render option which can be used with runAndRender or render
• request - the request (this is used to determine the context path)
• format - format of the output to be generated (html, pdf, xls, doc, ppt)
• getRenderOption : creates a render option which can be used with runAndRender or render
• request - the request (this is used to determine the context path)
• format - format of the output to be generated (html, pdf, xls, doc, ppt)
• genSVG - enable/disable the use of SVG graphics for chart generation
• runAndRender : run and render a document using the given report parameters and render options
• reportName - name of the report (without extension)
• parameters - parameters to be passed to the report engine running the report
• renderOptions - options specifying the output format
• locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used
• run : run a given report generating a report document (containing the data)
• reportName - name of the report (without extension)
• parameters - parameters to be passed to the report engine running the report
• reportDocumentName - name of the report document
• locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used
• render : render a report document into a specific output format
• reportDocumentName - name of the report document
• parameters - parameters to be passed to the report engine running the report
• renderOptions - options specifying the output format
• locale - a java.util.Locale object describing the locale the report is render to. If omitted or null the locale provided by grails is used

Configuring the plugin

The plugin supports configuration via the default Grails configuration file Config.groovy . You can also use per-environment configuration feature.

Currently supported options:

• birt.reportHome - the location where report files are stored. This can be absolute or relative; in the latter case it is relative to the web app root directory.
• birt.imageUrl - the location where temporary images for HTML pages are stored. Since images need to be accessible via the web app the path is always relative to the web app root directory.
• birt.generateAbsoluteBaseURL - enables the generation of absolute URLs if the URLs are taken from a HTTPServletRequest
• birt.baseUrl - the base URL to use for links if they are used within the report (e.g. drill-down). The baseUrl should be absolut, ie. starts with http: or you should set birt.generateAbsoluteBaseURL = true . The Format should be controllerName / actionName . The action get the name of the report via params.id .
• birt.useGrailsDatasource - a boolean enabling the use of the grails datasource as the report datasource (default is false). This can be modified on case by case basis by setting the property useGrailsDatasource of the service to true or false .
• birt.cacheSize - size of the memory cache to use for report generation (in mega bytes)

birt {
    reportHome = "Reports" // will be in the webapp directory during development
    imageUrl = "images/report" // this is a subdirectory of the images dir in the webapp directory, where BIRT stores the chart-images.
}

Troubleshooting

• Using Tomcat on linux without X-Server you must set in catalina.sh

  JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true "

• If you run into out-of-memory issues try to increase the PermGen Space. For Suns JVM you may use

  -XX:MaxPermSize=80m

• if you deploy on linux - you need to set writable permission on the birt engine directory

Releases

Version 3.7.2.0 - 4-Jul-2012

Added birt runtime jar which is now bundled with the plugin.

Version 3.7.0.1 - 15-Sep-2011

Added the ability to localize the generated reports based on the grails localization mechanism

Version 3.7.0.0 - 14-Aug-2011

Updated the BIRT version used to v3.7.0. This release does not need a special handling anymore as all OSGI plugins are bundled into a single jar not having plugin.xml descriptors anymore

Version 2.6.1.0 - 26-Oct-2010

Updated the BIRT version used to 2.6.1. The version number of the plugin will stay in sync with the BIRT version number.

Version 1.1 - 18-Sep-2010

Updated the BIRT version used to 2.6.0

Version 1.0 - 28-Jun-2010

Fixed download location

Version 0.8 - 19-Oct-2009

Skipped some versions in the changelog :-( therefore a wrap-up:

• splitted runAndRender into run and render method to allow reuse of compiled report documents to generate different output formats from the same data
• added the use of the grails datasource as the report data soruce (THX to Niels Stargardt for pointing this out)
• added the possibility to create renderOptions without a request to enable batch generation of reports, in this case the birt.baseUrl setting becomes important if links are use in the report documents
• fixed a bug while detecting absolute pathes on Windows (THX to Jean-Francois Dube for spotting this)
• fixed the download location of the BIRT runtime for the plugin installation
• added some javadoc to the service

Minor update due to missing compile time dependencies

Version 0.4 - 04-Aug-2009

Update of BIRT to version 2.5.0 following the Galileo release

Version 0.2 - 29-Mar-2009

First release to Grails repositories