BIRT, the Business Intelligence Reporting Tool for Java, is a powerful open source reporting platform. It's a good tool but it has bugs and an overall lack of good documentation and support. However, if you spend time with it to learn it's ins-and-outs then you'll discover it's very easy to do things with it once you know what to do!
In this blog I'm going to document some of the things that I think are important fundamental tasks in BIRT that were a lot harder than they should have been to get working. My hope is that I'll save you many days of struggle and frustration by providing some quick answers here.
I'd like to add first that I'm no expert in BIRT, and I certainly don't provide support for it. Also, much of what I've learned and have posted here is due to the help I've received from others.
1. How to get help using BIRT
It's great if you have a forum to ask questions and have them answered. The best resource out there right now for learning to use BIRT and resolving problems is the USENET group news.eclipse.org; subscribe to the e.birt group. You can post your questions on the newsgroup and typically your questions will be answered by someone within 24 hours using your favorite Usenet reader. A good free Usenet news reader is Mozilla Thunderbird, from those same people who make the Firefox web browser. You can get more information on how to register for a password for the newsgroup and access the Eclipse BIRT Newsgroups here. Be a good netizen and search the newsgroup before you post your question.
2. A good reference manual
|
It really helps to have a decent book on BIRT to get you started. This book is a good first step on how to do many tasks BIRT. However, it isn't good enough on it's own, that's why I'm writing this post. I suggest you use it as one of the tools in your arsenal when you start working with BIRT. (Disclosure: If you buy the book from this link to Amazon, a few pennies get thrown in my tip jar. Thank you!). |
3. How to output script debug information to the console
BIRT is a powerful tool because it has lots of events that you can write scripts for. When the event occurs BIRT faithfully runs your script. However, one of the problems that I have with BIRT is if there is something wrong with your script then BIRT stops processing your script for the event and just keeps going, without providing you with any useful feedback at all. I've come up with a workaround that lets me display output to the debug console.
Make a Java class. Call it something like MyLogger.
package com.davidjberman.birt.mytools;
public class MyLogger {
public static void log(String comment) {
System.out.println(comment);
}
}
In your BIRT script add an import package statement in the initialize event by clicking on the name of your report file in the Outline view, and then click on the script tab in the Report Design perspective in Eclipse. Select the initialize event from the drop down list at the top of the edit window. Add a line to import your package like this:
importPackage(Packages.com.davidjberman.birt.mytools);
Now anywhere inside BIRT you can insert a line to log debug output:
MyLogger.log("Hello, world!");
This is a big step, you've just gone from being in the dark to shedding some light on things. You will now be able to insert lines to output values for debugging, for example: MyLogger.log("Value of X is " + X); You can also insert lines to display output so you can see exactly how far your script ran before it was interrupted by an error. Finally, you can leverage structured exception handling in BIRT.
4. How to catch exceptions in BIRT
BIRTs way of catching exceptions is slightly different from Java because BIRT uses JavaScript. Here is what I have found as an effective way to catch exceptions in BIRT:
try {
DoSomethignNaughty = param["ThisParamDoesntExist"];
} catch (Oops) {
MyLogger.log("Exception accessing report parameter: " + e.message);
}
WARNING: In my experience BIRT does not always run the code in your catch block if something goes wrong in your Javascript. Sometimes BIRT just stops running your script. Use this approach as one possible tool but be aware of this snafu. If your code isn't working, add some lines to your script so you can see in your console output if a line of output displayed at the beginning of your script appears and another at the end to see if your script ran all the way through for that particular event.
5. How to access report parameters in BIRT
BIRT lets you define parameters for processing in your report. These parameters can be passed in by URL query string, for example:
http://www.davidjberman.com/notarealpage/myreport/?parama=hello¶mb=world
Inside your script you can access like this:
MyLogger.Log(params["parama"] + " " + params["paramb"]);
When you declare report parameters in BIRT you can specify some rules about how those parameters must be formatted, and you can even have BIRT pop up a window asking the user to select the desired report parameters before the report runs.
6. How to test if a parameter is missing in BIRT
This is a lot harder to figure out than one might expect.
Wrong answer: if (params["MyDesiredParameter"] == null) { ... do something ... }
This does not evaluate to null if you defined the report parameter and it defaults to null. The above logical test will return false but the value of the parameter will still be null. Instead, you have to do this:
Right answer: if (params["MyDesiredParameter"].value == null) { MyLogger.log("MyDesiredParameter is null!!!"); }
7. How to access parameters in a Scripted DataSet or Scripted DataSource
Scripted DataSets can have input parameters just like reports can have parameters. This lets you create something called Master-Detail report, also known as a correlated sub-query. You would use a master-detail report to do something like:
For each user: Display the user's name, and when the user last signed on)
For each post by this user on my forum: Display how many times the post was replied to and the date of most recent reply
This sort of a query has a master, the FOR EACH USER part; and a detail, the FOR EACH POST part. These are two different peices of information. You have an outer query, and an inner query which is dependant upon something from the outer query, which in this case would be the ID of the user in the outer loop.
BIRT lets you do this by giving you a second type of parameter: The DataSet parameter. Unlike Report Parameters, DataSet parameters are associated with a specific dataset only.
Report Parameters are accessed using the collection params. DataSet parameters are accessed using the collection inputParams.
| 1 |
Edit your dataset. Click on the Parameters tab on the left. Click NEW to declare a new parameter. Make sure to assign a default value, for a string use "". |
| 2 |
Add your nested table (the master-detail relationship, otherwise known as sub-table or correlated sub-query): Go to your report layout. Add a Table for your first dataset (the Master). Inside your table add a second detail row and drop another Table inside it. Associate the second Table with your second (detail) dataset. |
| 3 |
Define the relationship between master and detail records: Click on the grid for your details dataset. In the property editor, select the Binding tab. You should see that Data Set: has the name of your detail scripted dataset selected. Click on the Dataset Parameter Binding button. The DataSet parameter you defined in step 1 will appear. Click on it to select it, then click the Edit button. For the value, enter something like this: row["MasterTablePrimaryKey"] . Your nested table is inside a parent table, so row["xxx"] will be replaced with the value from the parent table in field xxx from the dataset associated with the parent row. |
| 4 |
Leverage the parameter in your scripted dataset:
/* In my script: */
PrimaryKeyFromParent = inputParams["NameOfDatasetParameter"];
|
8. How to use Global Variables in BIRT scripted DataSet
You can 'declare' global variables in BIRT by using a assigning a value to your variable in the initialize event of your report. For example:
importPackage(Packages.java.util);
globalvarToday = new Date();
Now you have a global variable called globalvarToday which is initialized to the current date. You can now access this anywhere in your report, including inside your scripted DataSets. Make sure you don't use the var token here or that will make your variable local to the initialize event scope only. Also if you declare your variable inside a try block that might also make it go out of scope, I haven't tried it.
I hope you found this helpful. I'll be posting more here as I learn more. Feel free to add comments with links to other resources.