Crystal Reports Integration Plugin for JIRA

Table of Contents Crystal Reports Integration Plugin for JIRA...1 Introduction...3 Prerequisites...3 Architecture...3 Limitations...3 Installation...3 Property File...3 Security Restrictions...3 License...4 Windows Installation (Installer Based)...4 Generic Installation (Zip File Based)...4 Final Steps...5 Usage...5 Appendix 1: Available Input Parameter Data Types...7 Copyright 2008 The Go To Group Page 2 of 7

Introduction The goal of this plugin is to allow JIRA users easy access to the sophisticated reporting capabilities of Crystal Reports. The plugin allows reports developed in Crystal Reports to be run from within the JIRA web interface. Prerequisites This plugin was developed and tested with: JIRA Enterprise 3.12.2 Crystal Reports XI Release 2 Other versions of these products may work with the plugin, but we have not tested other configurations. Architecture The plugin is a standard JIRA report plugin. It allows the user to select a report developed in Crystal Reports and saved in a folder on the JIRA server. Then, it uses Crystal Reports' Java Reporting Component (JRC) to run the report against the JIRA database, prompting the user for any input parameters. The user can then download the finished report in a choice of formats, including PDF. Since developing a report in Crystal Reports requires knowledge of the JIRA database schema, we have a separate document available, DbSchema.pdf, that has some basic background information on the schema. Limitations There are a few limitations and other points to keep in mind when developing a report in Crystal Reports to use with this plugin. The plugin supports all standard (non-binary) data types for input parameters. Sub-reports must get all of their parameters from the main report. Reports must use the same type of data source (JDBC) as JIRA, since the plugin tries to switch to the JIRA data source at run time. Installation Property File The plugin uses a property file for two pieces of information the security restrictions on the plugin, and the plugin license key. Security Restrictions Because a report developed in Crystal Reports has access to the entire JIRA database, any user able to access that report may see more information than they normally have access to in JIRA. If you wish to Copyright 2008 The Go To Group Page 3 of 7

restrict the use of the plugin to only users in certain groups, you will need to edit a file called crystal.properties. This file is provided as part of the installation package, and can be edited after the installation process. The file has one entry, listing the groups that are allowed to use the plugin. The lines below show the general format and an example. groups=group1,group2,... groups=jira-developers,jira-administrators As you can see, the format is a standard key-value pair. The value is a comma delimited list of the groups that are allowed to use the plugin. Be sure that none of the group names contains a comma. A sample configuration file is provided as part of the installation. It allows the jira-users group to use the plugin, which normally includes everyone in JIRA. License The plugin requires a license key. The license key must be in the property file, as follows: license=<your license key> An evaluation license key or a normal license key can be obtained by contacting info@go2group.com. Windows Installation (Installer Based) If you are running on Windows, you can use the installer, CrystalReportsIntegration.exe. It will ask you for your license key, the JIRA installation directory, and the location of the Crystal Reports configuration/license file. It will then place all the plugin files in the appropriate locations. Upon completion, the installer will provide you with the exact location of the configuration file, crystal.properties, and the report definition folder. Be sure to edit the configuration file if you wish to use different security restrictions, or need to change your license key. You should also double check the CRConfig.xml configuration file; if the reportlocation element is present, comment it out. You can place any reports created in Crystal Reports into the report definition folder at any time. Any report in the report definition folder will be available through the plugin. Generic Installation (Zip File Based) You will need to place several files on the JIRA server. In the steps below, the root JIRA directory is denoted as <JIRA_HOME>. On Windows, this directory would typically be located under Program Files for example, C:\Program Files\JIRA-Enterprise-3.12.1. 1. Unzip the plugin package file CrystalReportsIntegrationPlugin.zip. 2. Edit the property file crystal.properties to include your license key and any security restrictions. 3. Deploy the property file crystal.properties to <JIRA_HOME>/atlassian-jira/WEB- INF/classes. 4. Locate the Crystal Reports configuration file CRConfig.xml, which is installed with Crystal Copyright 2008 The Go To Group Page 4 of 7

Reports. 5. Copy CRConfig.xml into the directory <JIRA_HOME>/atlassian-jira/WEB-INF/classes. 1. The only important item in this file is the Crystal Reports license key. 2. If the element reportlocation is present in CRConfig.xml, comment it out. Otherwise the plugin will look in the wrong location for the report definition files. 6. Create directory <JIRA_HOME>/atlassian-jira/reports to contain Crystal Reports definition files. 7. Install any report definition files to the directory <JIRA_HOME>/atlassian-jira/reports. New report definition files can be added at any time. 8. Create directory <JIRA_HOME>/atlassian-jira/reports_out. This directory will hold temporary output from Crystal Reports. 9. Put the file crystal-integration-1.0.jar in the directory <JIRA_HOME>/atlassian-jira/ WEB-INF/lib, replacing any previous versions. 10.Put the file datetimepicker.js in the directory <JIRA_HOME>/atlassianjira/includes/g2g. 11.Put all of the JAR files from the lib folder of the zip package into the directory <JIRA_HOME>/ atlassian-jira/web-inf/lib. Final Steps Now, restart JIRA. The plugin will be available on the Browse Project page of any project, listed as Run Crystal Reports. Usage First, run the report by selecting Run Crystal Reports from the Browse Project page, as shown in Illustration 1. Illustration 1: Plugin in report list Now, select the report and output format (PDF, RTF, or CSV), as shown in Illustration 2. Again, the list of report names represents any report definitions found in the report definition folder. Copyright 2008 The Go To Group Page 5 of 7

Illustration 2: Report name and format selection Next, the plugin will prompt you for all of the input parameters for the report, as shown in Illustration 3. Each parameter will be listed, along with its data type, such as String, Date, or Number (see Table 1). Be sure to provide the proper data for each parameter; you can use the date picker for the Date or Date/Time fields. Illustration 3: Report Parameters Finally, the report is ready to download in the selected output format, as shown in Illustration 4. Click on the link to download the finished report. Illustration 4: Download Report Copyright 2008 The Go To Group Page 6 of 7

Appendix 1: Available Input Parameter Data Types Data Type String Date Date/Time Number Integer Boolean Table 1: Input Parameter Data Types Notes Text data Date without the time; use date picker to help with formatting Date with time; use date picker to help with formatting Numeric data Integer (whole number) data A true/false value. Input the text true to represent true; any other value will represent false. Copyright 2008 The Go To Group Page 7 of 7