How to Upgrade your BIRT Report to 4.4.2

By Shawnna posted 03-30-2015 19:06

Jama 2015.1 introduces an updated version of BIRT (4.4.2), and you’ll need to update your BIRT reports to work with this version. 

1. Download and install the BIRT RCP Designer (version 4.4.2). The report designer requires Java 1.6 or higher, installed in your Program Files (x86) folder.

2. Open BIRT. Open the report you would like to upgrade.

3. Expand Data Sources and double click on the listed data source to edit.

4. The following step is not required, but does allow for easier troubleshooting if you run into problems: click the Test Connection button to make sure that you have an active connection to the database.

If the connection is not successful, you will need to modify your Database URL, User Name and/or Password to connect.

5. Jama passes parameters to the report as Strings. The only exceptions are report_organizationId (or any organization Id) and report_userId (or any user Id). These parameters are integers. BIRT 4.4.2 will error out if the parameters are not the correct type, especially if the report calls an Oracle database. If you have report parameters, select one by clicking once on it.

6. In the Property Editor below the report designer, click Advanced and then scroll down to the Validation property. Enter “true” into that field. 

7. Open the parameter by expanding the double-clicking on the parameter.

8. Unless the parameter is a user Id or an organization Id, change the Data Type to String (if it isn’t already).

Click OK to save the change. Make the changes to all appropriate Parameters.

9. The parameters passed into each Data Set will also need to be changed. Expand the Data
section and double-click on a specific data set to edit.

10. On the left side, click Parameters to display the Parameters.

11. Double-click on a row to open a specific parameter, and change the Data Type to String (if not userId or organizationId).

Click OK to save. Repeat for all parameters.

12. To double-check that the query still works, click Preview Results.

You will receive an error if the query is now broken.

13. Save the report. You should get a Confirm dialog telling you that your report was created by an earlier version of BIRT and asking if you would still like to save it. Click OK.

14. Run the report to make sure that it works by selecting Run > View Report > As
. Scroll to the bottom of the report. If there are no errors in red, you are now ready to upload it to Jama.

15. Upload your newly upgraded version of the report to Jama and run it in all formats you want to output (i.e. Word, Excel, etc.). Any errors will appear on the HTML version, at the bottom. 

Common Problems

The report doesn’t run at all. You get a Java error instead.

This means that the report might have been modified but wasn’t upgraded. In the BIRT editor, make sure you change something (change the parameter data type to something, save, then change it back to a correct type and save again) in order to trigger the editor to save to the more recent version.

There are many red errors at the bottom of the HTML report

Sometimes, especially with Oracle databases the data sets reset and don’t use any aliases that might have been used in the query. This will lead to errors saying the table field can’t be found. To diagnose this, expand the data set to look at the field names.

If you are familiar with the field names, they might not look correct (they might be labeled name_12, name_3, etc.). If you aren’t sure, double click on the data set to open it. Click on Query and look at the query.

In this example, two items with the name “name” have been given aliases. When I view the Output Columns section, sometimes, the entries in the Name column (in red below) have reverted to their original field names without the alias. This will cause errors.

To remedy this, enter the Aliases from the query section into the Alias and Display Name columns above (you will have to click on each row to edit). The Alias and Display Name fields must match the Alias in your query exactly (it is case sensitive) in order to resolve the problem.

Unexplained errors

Usually, errors can be fixed as described above, but sometimes you will need to go into the xml to edit a field or table. The error should tell you the id of the table and/or field that is causing a problem.


Click the XML Source tab, click Ctrl+F and enter the id (here it would be 802 for the table) of the problem object. Once you have found the problem object, you can edit the data field or other property and save the report. Run the report from BIRT in HTML to make sure it works from within the BIRT editor before uploading it to Jama and testing it there.



11-27-2015 18:27

I think you should be ok with para_1 being an integer, but try it and see. I would recommend that you run it in the BIRT UI to check, but then double check by uploading the report into Jama and running it from there. I will often find no problems with my report until I upload it to Jama.

11-27-2015 11:21

Hi Shawnna,

I have a question related to data type of parameters of data set within my exisiting BIRT Report.

As I read the note "how to upgrade your birt report to 4-4-2", I understood:

For the report parameters, which were passed by Jama, they should be String except userid and organizationid, which are Integer.

However, my data sets have 2 types of parameters, one type is report parameter (which is clearly the case above). The second type is the data as result of other data set.

An Example of the second parameter type which I have : Data Set 1 returns documentID (which should be Integer, according to datatype of Jama schema. Data Set 2 takes this documentID as parameter (para_1).

Question: should the type of para_1 be changed to String too?



08-22-2015 21:45

Pradeep - 
To troubleshoot this, I would: 
1. In the BIRT UI, make sure your Data Source is the same Jama database that is attached to the Jama instance you will be uploading the report to. If they aren't the same dbs, you can't be sure they are identical.
2. Add a default to each of the report parameters so there are values when you run the data set (which is the next step). To add a default, double click on each Report Parameter, and add a value in Default Value. While you are there, double check that your data type is correct.
3. Go into the Dataset (by double clicking on the dataset name) and click on Preview results. If you have added defaults to the report parameters, you should get data back. If your query is bad, you would get an error here. I can't tell in the query you posted if the spaces between the query and subquery are entered here, but if it's in BIRT try removing them. Something I see quite a bit from MSSQL is that large integer values are returned to BIRT with commas, so you have to remove them in the query.
4. If you didn't get an error in step 3, I think that the problem is probably with whatever is getting passed from Jama through it's UI to the report and it's somehow causing a normally good query to choke. 
Hope this helps. I will post this in the other topic as well.
Shawnna Williams

08-21-2015 17:50

Hi Pradeep -

What do you mean it doesn't understand the scope? If the report doesn't work in Jama, it's usually because a parameter isn't set up with the correct data type or isn't set up with the correct name. But I am only guessing because I don't know what the error is. Can you post the error?

It's actually not that common to see an error from Jama when it runs without error outside of Jama. that's why I always upload it and test from there before letting users see it.


08-21-2015 16:36

I have a report which works in BIRT as well as MySQL work bench. But it give error in jama. It does not understand the scope. I posted the same question in the forum separately too @ Any guesses what/why this is happening?