developing report templates with jaspersoft studio

Collaborative Project Management.Designing Reports Your Way.

Report Template Design Overview

Designing and deploying report templates for Track+ is a five stepprocess:

1. Download an existing template similar to the one you like to create from the Track+ server.

2. Download some sample report data from the Track+ server to your local disk in XML format.

3. Start JasperSoft Studio and point the data-source to the sample data you have just downloaded.

4. Interactively design and test your new template locally, using the sample data as test input. Repeat until you are satisfied with the result.

5. Put all report template files plus some descriptive files into a single ZIP file and upload it to the Track+ server.

You can skip the first step if you want to start from scratch. You canskip the last step if you are satisfied with creating only local re-ports. In this case your report template cannot be run directly on theserver and will not be available to others.

Installing JasperSoft Studio

JasperSoft Studio is freely available as a ZIP file for non-Windowsbased systems, and as an installer executable for Microsoft Win-dows based systems at http://sourceforge.net/projects/jasperstu-dio. Prior to installing JasperSoft Studio, please make sure that youhave a Java runtime environment version 1.6 or up installed on yourcomputer. This can be obtained from the Oracle Java site, http://www.java.com.

It is important that you obtain a version that is compatible to thelibrary version used by Track+. The library version is displayed un-der the „System“ fieldset in the server status information window.Compatible means that it should not be much newer than theTrack+ library version as it then may generate code that cannot behandled anymore by the older library.

Step 1: Downloading Existing Template from Server

Usually it is easier to create a new template from an existing one,rather than start from scratch. On the Track+ server, by defaultthere are a number of report templates already available. Log inand go to toolbar icon „Reports“.

From the list of available templates choose one that comes closeto what you want to design and download it to your local computerby clicking on the Download icon in context menu.

The file you have downloaded is a ZIP-file. In order to use it youneed to unpack it using a ZIP utility like 7-Zip or the Windows unzip

utility. Once you have unzipped the file there will be a number offiles as shown below (here we have unzipped the existing template„Standard weekly report“). We will take a look at the meaning ofeach of these files a little later on.

Step 2: Downloading Sample Data

It is very convenient to test your reports during the design processusing sample data. Typically, you will in a rapid fashion repeatedlymake changes to your template design, compile the template, andrun the report to see what the result looks like.

To make sure that your report template matches the data formatprovided by the Track+ server, you download an XML file from aquery you executed on the server. If your report template runs toyour satisfaction on your local computer, you can be sure that it willalso run with no problems on the Track+ server later on.

To create a sample data set, run the report using a filter. Click on„Create report“, then choose a filter. Check that the data set you

Copyright 2013 Steinbeis GmbH & Co. KG www.trackplus.com [email protected] +49 7151 994 89 60

http://sourceforge.net/projects/jasperstudio/

http://sourceforge.net/projects/jasperstudio/

http://sourceforge.net/projects/jasperstudio



get is representative, and should not be too small or too large. Itshould be large enough to create at least two pages of output, andshould not be too large to not slow down the rapid development cy-cle. Check that you get a suitable result set with this filter by click-ing on “Create report” at the bottom of the filter configuration pop-up window..

Then create the XML data set by repeating the procedure and sav-ing the result to an XML file by clicking on “XML datasource” but-ton at the bottom of the filter configuration pop-up window.

Step 3: Creating the JasperReports Project

To develop your template you have to create a JasperSoft Studioproject. Open JasperSoft Studio.

Go to File > New > Project.

On the next screen select „Jasperreports Project“and click „Next“.Give a name to the project and save.

You have now a basic project structure.

Add a new source folder named „src“ by using the context menu,New > Folder.

2 Copyright 2013 Steinbeis GmbH & Co. KG www.trackplus.com [email protected] +49 7151 994 89 60

.

Use the context menu on your new project in the left navigationarea to modify some project properties.

Add the „src“ folder you just created to your source.

Copy the expanded ZIP file you downloaded previously into your„src“ folder. Your project should now look like shown here.

Step 4: Configuring the Data Adapter

It is convenient to test your reports during the design process usingsample data. To test the report templates with real data you haveto provide a data-source.

JasperSoft Studio supports a variety of data adapters, but only theXML adapter is useful if you are designing templates for the Track+server. Switch to the Repository Explorer view and click on the iconmarked below to define a new adapter.

Select the XML data adapter.

A new form appears which permits edit the properties of your newXML data adapter. Enter the values as shown below. For the XMLfile you enter the path for the file that you had previously down-loaded from your Track+ server.

Test your adapter and click on „Finish“.

You can now test if everything has been set up correctly. Doubleclick on the „.jrxml“ file in your project, like TrackReport-

Copyright 2013 Steinbeis GmbH & Co. KG www.trackplus.com [email protected] +49 7151 994 89 60 3

Standard.jrxml. In the design window you will see the cor-responding template.

Switch to the „Preview mode“ at the bottom of the design area. Atthe top select the data adapter you have just defined. Then click onthe little green arrow next to the data adapter selection list.

You will see the report with your sample data just as it would ap-pear on the server. You can try different output formats. The re-

spective programs like browser, Word, or Excel you need toconfigure for your JasperSoft Studio installation.

Step 5: Designing the Report Template

It is most efficient to start with an existing template when goingabout designing a new one. To start the design process, doubleclick on the jrxml file you want to take as a start.

On the screen a view similar to that shown below appears. Reportsare made up of „bands“. The document structure, showing thesebands can be seen in the window on the left named „Documentstructure“. For example there is a title band, a page header band, apage footer band, and a last page footer band which can be conve-niently used to print sums.


The actual report data is placed into the detail band. When runningthe report, the detail band is generated for each issue.

Example 1: Changing the Report Logo

As a first example let us try to change the logo that appears at thetop right of the first report sheet. You can see that the logo in thetemplate is placed in the „title“ band.

Click on the image and go to the „Properties“ windows on the low-er right.

Go to the „Image“ section. Here you see the name of the image filethat is being included.

The way it is shown here it refers to the file that is placed directlyin the template directory. The parameter $P{BASE_URL} is re-quired so that later on the system is able to find the image file atthe proper place.

In our example the image file is JPEG encoded and has a size of 253x 121 pixels. However, the image is scaled down to half its size(126 x 60 pixels) in the report template, which you can see on the„Common“ tab.

You can now place your own logo image file into the template di-rectory, include it in the template, and scale it to the size you like.It is recommended to use JPEG or PNG encoded files for images.

Once you have changed your template save it to disk (menu File >Save). Then switch to the preview tab.

If you have made any errors, you will get error messages in the bot-tom window.

After a little while the report should show up in the viewer programconfigured. In our example an Acrobat reader would be started andthe report is displayed there.

If this was all you wanted to do, proceed to Step 6 in order to de-ploy the modified report template on the server.

Example 2: Inserting a Custom Field

The report engine itself executes a query on the report data provid-ed to it before assembling the report. In case of an XML data-source as it is being used by Track+, the query is expressed in termsof an XPath path expression. The leaf nodes of the resulting dataset are mapped to JasperSoft Studio „fields“ which then can beused in the report template.

To map fields in the XML data set coming from the Track+ server toJasperSoft Studio fields, click on the „Fields“ node in the lower leftnavigation area. In the context menu select „Dataset and Query“.


You see the XPath expression of the current template and the resultset of this query.

In the illustration we have selected a node labeled „IssueNo“. Ifyou look at the bottom section of the same window you see a tablewhere this field „IssueNo“ is mapped to a template field named„IssueNumber“. Furthermore, it is defined that this field is of typeString.

You can add your own fields to your report template by draggingthem from the result node area to the fields table at the bottom ofthe window. From then on, you can refer to these fields using theplaceholder $F{yourfieldname}, for example $F{Is-sueNumber}.

Step 6: Deploying Report Templates on the Server

Once you are satisfied with your report template design you can de-ploy the template on the Track+ Server. This enables you and pos-sibly others to have a nicely designed report created directly froma report overview on the server, without having to download andconfigure anything locally.

Before you publish your new template to the server, make sure thatall required files are in one directory. Please pay attention to thefollowing:

1. Most important, you have to have the compiled report template file in the template directory. The compiled report template files have the ending „jasper“. We have set up our project such that they appear in the src directory.

2. Make sure you have a preview image of your report with

some sample data, about 800 x 550 pixels. For conve-nience, call it preview.gif. This enables the users of the Track+ system to have a look on how the report would look like without actually executing it.

3. Check that the proper texts are shown in file descrip-tion.xml.

Now place all files in the src directory into a ZIP file. Make surethat all files are at the topmost level of the ZIP file and that thereis no directory at the top level. You need to ZIP the files, not the di-rectory.

After you have created a ZIP file with the structure as shown above,log in to the server. Go to Reports and upload your report template.

Advanced Preprocessing with XSLT Style Sheets

The Track+ XML data file format may not be suited for a particularreport idea that you have. For example, the standard data structuredoes not support to print a pie chart on the number of issues as-signed to each responsible, or other similar presentations relyingon summarized data.

Nonetheless you can create reports like that by preprocessing theoriginal XML data file using an XSLT style sheet and a style sheetprocessor. Once you have tested your style sheet and report, you in-clude the style sheet into the report zip file, add its name to the re-port description file, and when you execute the report on theserver, it will use the same style sheet before it creates the report!

There is an example in the JasperSoft Studio distribution that usesa style sheet to create a pie chart report. In order to test and exe-cute your style sheet you have to install a style sheet processor onyour development computer. The Track+ server uses the Xalan pro-cessor which is freely available, so it may be best to use that aswell on your client. We will refer to this processor in the following.

The procedure to create reports based on your own data structuresis as follows:

1. Download some sample report data from the Track+ server to your local disk in XML format.

2. Develop your style sheet and create a new XML data file from the original XML data file, using the XSLT processor.

3. Start JasperSoft Studio and point the data-source to the sample data you have just created using your style sheet and the style sheet processor.

4. Interactively design and test your new template locally, using the sample data as test input. Repeat until you are satisfied with the result.


5. Put all report template files plus some descriptive files and your style sheet into a single ZIP file and upload it to the Track+ server.

This process is basically the same as outlined before for reportswithout data preprocessing, except for the additional step of creat-ing your own XML data file and pointing your data-source towardsit. Furthermore, you have to add your style sheet to the report pack-age that you upload to the server.

You can run the Xalan style sheet processor from the command linelike this:

java -classpath <yourPathTo xalan.jar>

org.apache.xalan.xslt.Process -in xmlSource

-xsl stylesheet -out outputfile

For example, if you have installed the Xalan jar file (xalan.jar) inC:\Program Files\Xalan, and you use the original ex-ported file from Track+, you would enter:

java -classpath C:\Program Files\Xa-lan\xalan.jar

org.apache.xalan.xslt.Process -in TrackReport.xml

-xsl chart.xsl -out TrackChart.xml

Steinbeis GmbH & Co. KGSoftware Quality SystemsEugen-Ruoff-Str. 3071404 Korb

Tel.: +49 7151 994 89 60Fax.: +49 7151 994 89 61E-Mail: [email protected]: http://www.trackplus.com

Steinbeis Software Quality Systems U.S.A.54688 Dawn DriveOsceola, IN 46561U.S.A.

Tel.: 574-968-7619Fax.: 574-968-6430E-Mail: [email protected]: http://www.trackplus.com
