® IBM Software Group © 2009 IBM Corporation BIRT Integration with EGL v P. Michael Virga

2 Last update: 8/02/2009 Business Intelligence and Reporting Tools (BIRT)  An Eclipse-based open source reporting system  A mature Eclipse technology  Can create pdf/html reports  Can generate complex report design layouts:  Lists  Charts  Cross-tabulation  Letters  Documents  Compound reports.  BIRT home page:

3 Last update: 8/02/2009 BIRT Elements and Integration out in BIRT Design File (xml) EGL JavaGen Application Generated report (html/PDF) EGL BirtHandler EGL Program BIRT Report Design

4 Last update: 8/02/2009 Report Design Tool  Report Design Perspective  Create reports:  From scratch  Using pre-fab layouts and templates (see below)  Tie reports directly to data sources:  Within Report Design perspective, can preview reports  From EGL BirtHandler and Program or Web page, can bass array to report  Each report element can customized extensively  U.I.  Expressions (counters and accumulators)  Straightforward and Eclipse development process

5 Last update: 8/02/2009 Report Design Preview  Content Area tab when in Report Design perspective  Allows you to analyze report with full data in view  Use as either:  Standalone Report – if running BIRT XML  Design development tool – if intending to execute BIRT report from EGL:  Program  JSFHandler

6 Last update: 8/02/2009 BirtHandler  EGL Part type  Called from EGL program or JSFHandler  which can pass an EGL dynamic array into the BirtHandler  The BirtHandler interacts with BIRT standard events  openEvent – reference to BIRT report data set (a data source)  fetchEvent - reference to

7 Last update: 8/02/2009 EGL Program That Invokes BirtHandler  Report Design Perspective  Create reports:  From scratch  Using pre-fab layouts and templates (see below)  Tie reports directly to data sources:  Within Report Design perspective, can preview reports  From EGL BirtHandler and Program or Web page, can bass array to report  Each report element can customized extensively  U.I.  Expressions (counters and accumulators)  Straightforward and Eclipse development process

8 Last update: 8/02/2009 BIRT Lab and Workshop  Let’s create a PDF report like this, using BIRT and a batch EGL program  The steps to do this start on the next slide.

9 Last update: 8/02/2009 Workshop and BIRT Steps Before you start there are several assumptions: You are in a workspace that contains the EGLWeb workshop project. If not you’ll need to create a new BIRTTutorial Dynamic Web Project. Derby is installed and in the C:\databases\EGLDerbyR7 folder. A connection to that database is already created. The data access application has been created for the Customer Table. This workshop is written using WebSphere as the Application Server. Tomcat should work as well. Ok. Here are the steps to getting BIRT to work: 1.Download the BIRT Runtime 2.Configure your project 3.Watch the BIRT Report Design tutorial 4.Create the Report_Design file 5.Create the BIRTHandler 6.Create the EGL Program that calls the BIRTHandler 7.Test

10 Last update: 8/02/2009  BIRT Runtime Download  Download BIRT runtime, birt- runtime-2_3_2_2.zip, from:   Note – there are a lot of different versions of the Runtime. Please only download the one that matches the version of RBD as follows:  RBD v7.1  BIRT v2.1.2  RBD v7.5  BIRT v2.3.0  RBD v7.5.1  BIRT v  From the BIRT site, select:  Recent Builds Page

11 Last update: 8/02/2009  Project Configuration – 1 of 5  Unzip the downloaded Report Engine file into a directory on your PC  Set the project’s build descriptor option birtEngineHome to the location of the Report Engine directory in the BIRT runtime:  e.g. C:\birt\birt-runtime-2_3_2_2\ReportEngine  Note that ReportEngine is a folder created by unzipping the download  Also, IMPORTANT, make sure the j2ee property is set to No.  Verify/Set your EGL Project Capabilities for BIRT  From Window > Preferences  General –Capabilities  Select Advanced  Expand EGL Developer and select EGL BIRT  Click Apply then OK

12 Last update: 8/02/2009  Project Configuration – 2 of 5  Verify that your Default EGL Project Features Choices is BIRT enabled  From Window > Preferences  EGL  Check EGL with BIRT report support  Click Apply and then Ok  Enable BIRT report support for the EGL project you want your report to run in:  Select your project, i.e. EGLWeb, right mouse click.  Select Properties, and scroll to EGL Project Features  Check EGL with BIRT report support  Click Ok.

13 Last update: 8/02/2009  Project Configuration – 3 of 5  To generate PDF reports, download the (latest) iText jar file and add it to the project’s src class path. It can be downloaded from: ext/files/  Once you’ve downloaded the file, open the Resource Perspective, and:  From Windows, copy the file to your:  \src\ folder … and into the …  \WebContent\WEB-INF\lib folder  Close the Resource Perspective, and return to the Web Perspective

14 Last update: 8/02/2009  Project Configuration – 4 of 5  The last step in configuring your project is to copy 5 jar files from the BIRT Runtime Library to your WEB-INF\Lib to synchronize the downloaded version with the version packaged with RBD.  From the Resource perspective  Select the WEB-INF\Lib folder, right mouse click, and select Import.  Select General, File System and use the Browse button to navigate to the BIRT folder you installed BIRT Runtime in. i.e., C:\Birt\birt- runtime- 2_3_2\ReportEngine\lib  Select the following jar files:  Coreapi.jar  Engineapi.jar  Js.jar  Modelapi.jar  Scriptapi.jar  Overwrite the ones already there  Note: If you skip this step, you will see error messages that say “unable to load report engine…”  One last step and you are done Next Slide:

15 Last update: 8/02/2009  Project Configuration – 5 of 5 Add your data base driver as an External Jar In this case Derby.jar Click Add External JARs… Button Navigate to the location of Derby.jar Select Derby.jar Click Open.

16 Last update: 8/02/2009  Watch the BIRT Tutorial The BIRT site has two excellent tutorials for learning how to use the Report Design tool: Flash movie with annotations   Step for Step tutorial

17 Last update: 8/02/2009  Create Your Report Design Layout \ reports \  From Project Explorer, create a \ reports \ folder under your Report Project, i.e. EGLWeb project Report Design perspective  Open the Report Design perspective File  From the File menu, create a new, report reports folder  For the parent folder, specify the reports folder customerList.rptdesign  Name the report: customerList.rptdesign Next  Click Next  Note the abundance of cool report templates My First Report  Select My First Report Finish  Click Finish

18 Last update: 8/02/2009 Report Design perspective You will now have a new default template for your BIRT report

19 Last update: 8/02/2009  Create the Report’s Data Source and Data Set  Open the Data Explorer view  Right-click over Data Sources and create a New Data Source  As a Scripted Data Source  Named: scrDataSource  Right-click over Data Sets and create a New Data Set  Named: scrDataSet  With the four Output columns shown  And their Display Names  When you are finished, your Data Explorer should show the following defined resources

20 Last update: 8/02/2009  Layout the Report Using the Data Set  From the Content Area, select the Layout tab  Delete the two default rows for the column heading and data (not the header or footer row)  From the Outline View, Select drag and drop the scrDataSet into the top left-hand corner of the report layout under the header row, where it will create a report table as shown below  Optionally open the Palette view on the left

21 Last update: 8/02/2009  Customize the Column Headers and Row Font  From the Content Area, click the left-most cell to select the column header row  From the Property Editor – customize the properties  Change the Font type and make the column headers bold  From General, change the row background color  Then, select the detail row, and change it’s font

22 Last update: 8/02/2009  Add a Total Expression  From the Palette, drag Aggregation element from Quick Tools into the Report, and add it to the footer row  From the Aggregation Builder, Add:  Display Name: Total  Function : Count  Click OK

23 Last update: 8/02/2009  (Optionally) Edit the Report Heading  Customize one or more of its General properties:  Background color  Bold text  Centered  Text Color: White (if you make the background darker)  Save your changes and switch back to the EGL Perspective

24 Last update: 8/02/2009  EGL BIRTHandler programs From Project Explorer, create a new EGL BIRTHandler, in the programs folder, named: arrayHandler ***Notes  Copy paste the code in the ***Notes  Review the inline comments, note the following:  The handler is passed a dynamic array of customer records  Which it uses with the two reserved functions that fire automatically:  openFunction  fetchFunction  fetchFunction adds values to the BIRT design report by calling the setColumnValue function (built into the BIRTHandler)

25 Last update: 8/02/2009  EGL Program Calling BIRTHandler programs From Project Explorer, create a new, EGL Program in the programs folder, named: BIRTHandler, named: birtReportProgram1 ***Notes  Copy paste the code in the ***Notes  Review the inline comments, note the following:  You must reference your input (Report Design file), and output file – as shown  You retrieve and process your dynamic array data (in this case, a sub-set of the Customer table)  You declare a variable of type: BIRTHandler, with the specific value shown  You pass your dynamic array to the BIRTHandler  And you call the EGL built- in functions to create the report  GENERATE Your Project (Ctrl + G)

26 Last update: 8/02/2009  Produce the PDF Report From Project Explorer, open the Java Resource:src folder, from the \programs\ sub-folder:  Select birtReportProgram1.java  Right-click and:  Run as  Run Configurations…  Run dialog will be opened  Select Java Application  Right Mouse Click and Select New

27 Last update: 8/02/2009  Produce the PDF Report  Click Classpath tab  Select EGLWeb (or your Report Project under User entries  Click Remove

28 Last update: 8/02/2009  Produce the PDF Report  Select User Entries  Click Add Projects

29 Last update: 8/02/2009  Produce the PDF Report  Check EGLWeb (or your Report Project )  Click OK

30 Last update: 8/02/2009  Produce the PDF Report  Click Add JARs Select All the jar files in WebContent/WEB-INF/lib directory Click OK

31 Last update: 8/02/2009  Produce the PDF Report  The Classpath should look something like this:  Checklist:  1. The Report Project  2. The Runtime Jars from WEB-INF\lib  3. iText jar  4. derby.jar

32 Last update: 8/02/2009  Produce the PDF Report  Click Run  This should create the PDF shown here : Optional things to do: Create an html page (see next slide) From the tutorial, learn how to: Customize the column widths and row height Outline the State data Add a label to the Total Count() value Do a grouped report

33 Last update: 8/02/2009 HTML Report In this section we have just scratched the surface of what you can do with BIRT and EGL.

34 Last update: 8/02/2009 EGL JSFHandler Calling BIRTHandler You can – if your project requirements dictate, call BIRT from a JSFHandler. You will need to configure your project to call BIRT. Below is the Use Case model for this. Let’s see what we need to do to make this work. Special Thanks to Matt Heitz, for this one! Output PDF Selected rows

35 Last update: 8/02/2009  EGL JSFHandler Calling BIRTHandler – Configure Your Project – 1 of 2 Complete the following four tasks (starting on this slide) 1.Edit the deployment description for the Web module (web.xml).  Add a new EnvironmentVariable named birt.report.engine.home of type java.lang.String.  The value should be the location of the BIRT runtime.  This is the same value that you would place in the build descriptor option birtEngineHome. 2. (If you are using WebSphere Application Server)   Edit the EAR's deployment descriptor (application.xml). PARENT_LAST.  Set the web module's classloader policy to PARENT_LAST. 3. Ensure that the EGL program uses absolute paths to the report design files. Relative paths will not work. See the JSFHandler for an example of this

36 Last update: 8/02/2009 Step 4. Verify/Add the EGL Runtime Data Source EGL JSFHandler Calling BIRTHandler – Configure Your Project – 2 of 2 This may have already been set for you in a previous workshop. If so, verify that the database location is correct and click OK. If this is empty, select the Input/modify values manually and Enter the information as shown. Then click OK.

37 Last update: 8/02/2009 EGL JSFHandler Calling BIRTHandler – Create the Page and JSFHandler From Project Explorer: Create a new.JSP page, named: testBIRT.jsp Modify the default page header text Edit the JSFHandler ***Notes Delete the existing code, and replace it with the code in the slide ***Notes Note the following:  Absolute path to the report_design file .pdf output file  sel int[0]; array – used to catch the rows the users select with the dataTable checkboxes  Looping through the sel[0] array, to populate the customersOut array, which is eventually written to the pdf file Save your changes.

38 Last update: 8/02/2009 EGL JSFHandler Calling BIRTHandler – Create the Page From Page Designer / From Page Data –  Drag the customers[] array onto the page, and select some columns – as output (read only) fields  With the entire dataTable selected, from Properties - Row actions  Click: Add selection column to the table  This will add a checkbox to the dataTable  With the checkbox selected, from the Value:  Click the icon  Select the sel int [] array Finally - Drag the writeToPDF function on to the page, where it will render as a Submit Button

39 Last update: 8/02/2009 Run the Page Run the page on the server. Select any # of rows, and press: writeToPDF - this should create a file on your c:\ drive, called: jspreportOut.pdf. Open the file C:\jspreportOut.pdf Selected rows

® IBM Software Group © 2009 IBM Corporation Trouble Shooting

41 Last update: 8/02/2009 Run the Page (WAS 6.1 NoSuchMethodError problem solution) If you got NoSuchMethodError in WAS 6.1, try to change the class loader order: 1.Expand Applications – Enterprise Applications 2.Click your Enterprise application name 3.Click Manage Modules under Modules 4.Click your web module 5.Select Class loaded with application class loader first 6.Restart your enterprise application.

42 Last update: 8/02/2009 Trouble Shooting  Need to add in the next version

43 Last update: 8/02/2009 For More Information  EGL Café  There are books available on BIRT. Check them out!  BIRT Home :  Project InterChange File (PIF) that Accompanies this Presentation. PIF is :