Jasper Report Plugin

Name	Jasper Report Plugin
Vendor	Bob Swift and other contributors
Authors	Bob Swift
Homepage	http://confluence.atlassian.com/display/CONFEXT/Jasper+Report+Plugin
Issue Management	http://developer.atlassian.com/jira/browse/JSPR
Categories	Content Macros
Version	3.0.1
Availability	Confluence v2.2 to v2.10-m1
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Free
Release Docs	http://confluence.atlassian.com/display/CONFEXT/Jasper+Report+Plugin
Java API Docs	n/a
Download Source	http://svn.atlassian.com/svn/public/contrib/confluence/jasperreport-plugin/trunk
Download JAR	jasperreport-plugin-3.0.1.jar

Additions and corrections to above:

Confluence compatibility	2.2.2+ only, tested on 2.2.8 and 2.3dr2
JVM requirements	Java 1.4 and above
Dependencies	Jasper Report Image Servlet
Installation requirements	Confluence Repository Client or upload from Confluence's administration console. Cannot be installed in /WEB-INF/lib

Description

Provides integration of Jasper Reports capability with Confluence. Allows Confluence users to compile, fill, show, and export a Jasper Report within Confluence pages . This support is provided using Jasper Reports 1.2.6. The companion plugin Jasper Report Image Servlet must also be installed for the proper display of images.

Installation

This macro provides programming access to server data, so you may need to consider restricting access. See macro-security for documentation and example usage.

Pre-requisites

The following must in installed in .../WEB-INF/lib. Make sure earlier versions are removed. Restart Confluence after the updates are made. Later versions of these libraries will probably work as well.

Installation customization

The classpath that Jasper Reports uses to compile reports can be customized. Normally, this should not be necessary. To customize, set the system environment variable jasper.reports.compile.class.path prior to starting Confluence.

Documentation

• Also see the Notation guide

Overview

• Jasper Reports is an open source reporting framework. A report design is represented by an xml document. The {jasperreport} macro allows for Jasper Reports designs to be used in Confluence. The Jasper Reports documentation should be used to understand how to create and use reports. The following is a summary picture from the documentation to help explain the relationship to the support offered here.
  

Features supported

• Compiling a report design, filling in the data, and displaying the report
  • Display is via export to HTML for display in Confluence
• Loading an existing report (compiled design) or filled in report (print) and displaying the report
  • Optionally allows for performance saving by eliminating a compile for every page view
  • Optionally allows for performance saving by eliminating retrieving data for every page view
  • Optionally allows for point-in-time saving of reports and report data
• Automatic saving and re-using reports or print reports
  • Includes ability to determine if a report design has changed and automatically recompile
• Allow images to be displayed on reports
• Allow data from a data source
• Supported Jasper Report capabilities
  • Report parameters using strings, integers, floats, and JasperReport
  • Support for reports with sub-reports

Report support matrix

Parameters

• dataSource - Specify the datasource (jndi name) defined in the application server. Do not use the standard prefix (java:comp/env/jdbc/) as it is added automatically. Formerly called the jndi parameter which will remain valid for upward compatibility. You may need to consult with your administrator to get this name.
• designFile - Location of the Jasper Report design xml. If not specified, the macro body is used.
  • ^attachment - Data is read from an attachment to the current page.
  • page^attachment - Data is read from an attachment to the page name provided.
  • space:page^attachment - Data is read from an attachment to the page name provided in the space indicated.
  • filename - Data is read from the file located in /script/reports/filename. Subdirectories can be specified.
• reportFile - Location of the Jasper Report compiled design. The reportFile will be used as directed by the 'use' parameter. If a filename is specified, the file could be updated based on the 'keep' parameter setting.
  • ^attachment - Data is read from an attachment to the current page.
  • page^attachment - Data is read from an attachment to the page name provided.
  • space:page^attachment - Data is read from an attachment to the page name provided in the space indicated.
  • filename - Data is read from or written to the file located in /script/reports/filename. Subdirectories can be specified.
• printFile - Location of the Jasper Report print file (a filled in report). The filled in report will be used as directed by the 'use' parameter. If a filename is specified, the file could be updated based on the 'keep' parameter setting.
  • ^attachment - Data is read from an attachment to the current page.
  • page^attachment - Data is read from an attachment to the page name provided.
  • space:page^attachment - Data is read from an attachment to the page name provided in the space indicated.
  • filename - Data is read from or written to the file located in /script/reports/filename. Subdirectories can be specified.
• exportFile - Location of the Jasper Report export file (a filled in and exported report). If a filename is specified, the 'exportFormat' parameter defines the type of export. For export to an attachment, the user must be authorized to add attachments to the page specified.
  • ^attachment - The report is exported as an attachment to the current page.
  • page^attachment - The report is exported as an attachment to the page name provided.
  • space:page^attachment - The report is exported as an attachment to the page name provided in the space indicated.
  • filename - The report is exported as a file located in confluence home directory/script/reports/filename. Subdirectories can be specified.
• exportFormat - Defines the format of the export. Default is is to use the extension of the exportFile if it is valid. Otherwise the default is'pdf'.
  • pdf - (default) Export format is 'pdf'.
  • xml - Export format is 'xml'.
• exportVersion - Defines the the versioning mechanism for exported reports.
  • new - (default) Creates new version of the attachment. For file based exports 'new' has the same effect as 'keep'. this is produced on each page view!
  • overwrite - Overwrites existing report and, for attachments, removes all previous versions! To overwrite an existing attachment, the user must be authorized to remove attachments for the page specified.
  • keep - Only creates an new export if an existing export of the same name does not exist. An existing attachment will not be changed and an existing file will not be updated.
• use - Specify what report format to use.
  • automatic - (default) Use the best choice based on the other parameters and existence of files. This includes verifying the compiled version is current with respect to the current content of the design source (body or designFile) and recompiling it if the compiled version is old.
    • print provided printFile is specified.
    • report provided reportFile is specified and it is current with respect to the design source.
    • design provided it is provided in the body or the designFile.
  • design - Use the design xml in the body or specified by designFile.
  • report - Use an existing compiled version of the design xml.
  • print - Use an existing filled in version of the report.
• keep - Specify what report format to keep for later use.
  • none - (default). Do not keep any intermediate files
  • report - Keep the compiled version of the design provided the reportFile is specified as a file.
  • print - Keep the filled in version of the report provided the printFile is specified as a file.
  • all - Keep both the report and print versions provided the corresponding file names are provided.
• showDesign - Default is false. Set to true to show a panel with the design xml source (if available).

Direct file access The script macros access the script directory in Confluence home for file access. The jasperreport macro uses the script/reports directory for file access.

Report parameters

Jasper reports provides the capability for reports to have parameters that are used at fill time to customize a standard report. The parameters are provided by the application that is requesting the report. For {jasperreport}, parameters are set from the macro parameters. {jasperreport} supports the following class names:

• String
• Integer
• Float
• JasperReport

{jasperreport} provides the following pre-defined parameters:

• ReportDir - a File object representing the default reports directory
  • For example, this can be used to provide access to images

    <imageExpression class="java.io.File"><![CDATA[new File($P{ReportDir}, "images/execute.gif")]]></imageExpression>
    

• ConfluenceDomain - a String object representing the configured URL for this Confluence instance (Server Base URL).

Usage

Example - Simple report from a data source

{jasperreport:datasource=TestDS}

... xml representing a valid Jasper Report design

{jasperreport} 

Example - Using an attached design

{jasperreport:datasource=TestDS|designFile=^Simple.jrxml}
{jasperreport} 

Example - Saving and reusing a compiled report

{jasperreport:datasource=TestDS|designFile=^simple.jrxml|reportFile=example/simple.jasper|keep=report}
{jasperreport} 

Example - Exporting the final report as a attachment with overwrite

{jasperreport:datasource=TestDS|designFile=^simple.jrxml|exportFile=^ExampleReport.pdf|exportVersion=overwrite}
{jasperreport} 

Example - Basic Report: using a String parameter

• the state_abbr parameter is passed to the report as a String:

  {jasperreport:datasource=TestDS|designFile=example/BasicReport.xml|state_abbr=CA}
  {jasperreport}  
  

Example - Order and Referral History (in columns): using an Integer parameter

• Note that reports are keep for use in the Multi Report example

  {section}
  {column} 
   
  h3. Order History - {color:blue} {sql:datasource=TestDS|table=false} 
  select first_name, " ", last_name from CUSTOMER where customer_id=1 {sql} {color}
  
  {jasperreport:datasource=TestDS|designFile=example/OrderHistory.xml|reportFile=example/OrderHistory.jasper|
  customer_id=integer(1)|keep=all} 
  {jasperreport}  
  
  {column}  
  {column}  
   
  h3. Referral History - {color:blue} {sql:datasource=TestDS|table=false}
  select first_name, " ", last_name from CUSTOMER where customer_id=1 {sql} {color}
  
  {jasperreport:datasource=TestDS|designFile=example/ReferralHistory.xml|reportFile=example/ReferralHistory.jasper|
  customer_id=integer(1)|keep=all} 
  {jasperreport} 
  
  {column}
  {section}
  

Example - Multi Report: using JasperReport parameters

• The OrderHistory and ReferralHistory parameters are passed to the report as JasperReport objects loaded from the compiled report files provided:

  {jasperreport:datasource=TestDS|designFile=example/MultiReport.xml|reportFile=example/MultiReport.jasper|
  customer_id=integer(1)|keep=all|OrderHistory=JasperReport(example/OrderHistory.jasper)|
  ReferralHistory=JasperReport(example/ReferralHistory.jasper)} 
  {jasperreport}  
  

Recommended use of design, report and print files

• Use page body or attachments for storing design xml
  • changes are versioned
  • data is saved with Confluence backups
• Use keep and reportFile parameters to store compiled reports in the file system to reduce system resource use. Use the default setting (use=automatic) so that compiled report will be automatically updated if the design changes. Also enables the multi-report feature for more complex reports that imbed other reports.
• Only use the printFile parameter if you want keep a "point-in-time" report or you have automation that periodically (hourly, daily, weekly, monthly) deletes the file so that it gets refreshed with new data (this will be done automatically unless use=print is specified).

Customer example report design source

• The report designs and instructions for creating the supporting database can be downloaded from Generating online reports using JasperReports

Gallery

Screenshots
Jasper Reports macro flow	Jasper Reports - design picture	Group Report
Multi Report	Order and Referral History	Basic Report

Open Issues

Atlassian Developer Network JIRA (6 issues)
T	Key	Summary	Reporter	Assignee	Pr	Status
	JSPR-1	Problems with report encoding and special characters	Christian R�ckert	Bob Swift		Open
	JSPR-2	Support jasper report data from table data	Bob Swift	Bob Swift		Open
	JSPR-3	Support jasper reports with embedded charts.	Bob Swift	Bob Swift		Open
	JSPR-4	vriable type support	apolo	Bob Swift		Open
	JSPR-5	Digester JAR download link is bad	Andy Brook	Bob Swift		Open
	JSPR-6	Unable to configure Jasper Plugin with Oracle OC4J 10.1.3	Karen Fishwick	Bob Swift		Open