Use of Birt

Using BIRT for reporting in the ClassiX system

• Reporting in ClassiX
• Edit BIRT reports
• Troubleshooting
• Performance improvement of the reports

Note
Currently, only version 4.6.0 (OSGI only) and 4.7 upwards (POJO only) are supported. If you have installed another version, you can uninstall it and then install version 4.6.0.

Reporting in ClassiX

Instructions for creating a report from within the ClassiX system. Contains simple list reports and describes how to insert additional columns into a list or delete columns. Also describes how to create a report completely free and how to add a report to your favourites.

This document provides an overview of recommendations for new BIRT reports.

Procedure for column name changes

If access expressions for columns are changed in ClassiX or new columns are added to the BIRT report, the BIRT report has to be adapted as well. This is especially important if the access expressions change, otherwise the columns of the BIRT report cannot be filled with data anymore. To check if new columns have been added to ClassiX or if the access path has changed, the function "Layout Comparison" can be used (see also toolbar section on the report module page and in the PDF documentation). For the layout comparison, a new layout file is created from the current ClassiX list into the directory of the environment variable CX_REPORT_DATA and compared with the layout in CX_ROOT_DIR\BIRT that was defined as current until then. Depending on how the environment variable CX_DIFF_EDITOR is set, the comparison is performed with the Windows-internal Diff program (FC) or with ExamDiff (or any other comparison tool that is defined).

Edit BIRT reports

Quick guide to creating a report with grouping and diagrams.

All information on using BIRT and creating reports in the ClassiX system can be found in the PDF documentation. To make it easier to get started, a tabular and graphical overview has been created. The links refer directly to the revision pages in the PDF documentation:

Tabular overview

Graphical overview

Performance improvement from the reporting side

The performance of BIRT reports is influenced from different angles:

• Performance of the BIRT engine
• Performance of data extraction from ClassiX
• Performance of BIRT data access to the data source
• Performance of the report itself

The performance of the BIRT engine can be improved by not restarting the engine every time a report is generated, but starting it once at the beginning and then just using it.

On the last point, this document was created to provide an overview of the performance of different objects in the report.

Troubleshooting

There are various reasons why a BIRT report cannot be called up from ClassiX:

• Configuration error during the installation of Birt
• Authorization problems
• Error during communication between ClassiX and BIRT
• Error in the BIRT reports
• Error in ClassiX or BIRT code

Ideally, ClassiX creates or opens a BIRT report without any further user intervention. However, depending on the error case, ClassiX receives too little information to display a clear error message. In this case the communication between ClassiX and BIRT must be checked and the error message of BIRT or the calling program must be analyzed. There are two tools for this:

• Analysis of the ClassiX log file (see Logging). Specifically, when calling Birt, entries are written in the area cx.process. Especially the call as well as the parameters and the return code of the started application are logged (if necessary increase the logging level). Please check if the passed input files exist. You can also repeat the entire call from a console.
  
• Open the debug console. By setting the environment variable CX_BIRT_DEBUG_CONSOLE, a console is opened when Birt is called, on which the application displays possible problems. The console closes again if the call was successful. In the output of this console you should pay attention to the following points:
  
  • Do errors already appear when calling? (Program not found, Java not installed correctly, PATH not set correctly)
  • Does java not find certain classes? ("Class not found": Classpath for Birt or ClassiX libraries not set correctly, attention: the directory %BIRT_HOME%\ReportEngine\plugins must not be added to the classpath, otherwise error messages will be displayed)
  • Which parameters are transferred? Do the files or parameters exist?
  • Is there an exception?

Since the upgrade to BIRT 3.7.2, errors may occur when starting ClassiX without administrator rights. In this case the configuration of BIRT 3.7.2 and higher should be considered.

If a report is generated but does not contain any data, check CLASSPATH variable (see Installation Birt-Runtime). If the "addons" folder is missing in the classpath, the report layout is generated successfully, but the tables remain empty.

Error in the communication between ClassiX and Birt and error in the Birt code

The following table shows the error code, error message and possible solution strategies for an error in the Birt code or in the parameter transfer between ClassiX and Birt

Please note that every time the ReportEngine crashes, a dump file is created which may help to find the solution to the problem. This dump file is stored in the "Temp" directory (environment variable "Temp") and has the name "classix-ExecuteReportNumber.dmp".

Code	Error message	Solution
1	Wrong number of parameters	There is probably a problem with the Java libraries required by BIRT. So the problem could be either that the BIRT-HOME is set incorrectly, that the Birt interface is not reachable or that the Java Runtime Engine (JRE) is not reachable. Please check the following: First set the debug console to true, which will give you detailed error messages: Set "SET CX_BIRT_DEBUG_CONSOLE=TRUE" in the calling batch file. Now please check all environment variables: All important environment variables are listed here. Please check in particular if: The BIRT HOME environment variable is not set correctly (C:\birt-runtime-osgi-4_6_0 or C:\eclipse\birt-runtime-osgi-4_6_0). Also pay attention to possible errors in the spelling (hyphen/underscore) The Java Runtime Engine is not included in the PATH environment variable, so Java applications cannot be started (this includes BIRT). Check if "Java_Installation Directory/jre/bin" is set in "ClassiX_Start.bat" or as environment variable "Path" (example: "C:\Program Files (x86)\Java\jre7\bin"). Otherwise, in the calling start file, add the line "SET PATH="Java_installation_directory\jre\bin";%Path%" added. If the Debug Console is turned on, you would also have to enter an incorrect path or no path at all to the Java installation directory. One of the following files may be missing: data-xml, rptdesign name, output-pdf name. This can be checked by debug console. To do this, the line "SET CX_BIRT_DEBUG_CONSOLE=TRUE The file "BirtInterface.jar" is not available in the "\Bin\4.5" directory The file "BirtInterface.jar" is not up-to-date. It should have been created in 2012.
2	invalid XML	Probably JAVA is not (correctly) installed For verification or if this does not help, set the debug console to true, which will give you detailed error messages: Set "SET CX_BIRT_DEBUG_CONSOLE=TRUE" in the calling batch file.
4:	Birt reported error during execution (Engine Exception)	Please check the following: The report may have been created with a Birt version that is currently not supported. Currently, only Birt reports created with Birt version 4.6.0 and below are supported. You can check this in the report. The report must have version 23. To do this, go to the xml-tab in the main menu of Birt and check if one of the first lines is like this: lns="http://www.eclipse.org/birt/2005/design" version="3.2.23" id="1"> If not, the version must be manually changed to 3.2.23 and it is recommended to downgrade the Bird version to avoid further problems. The following error message is issued in CX_DEBUG_CONSOLE: "Failed to initialize emitter". This may be due to the fact that there are no write permissions in the folder where the xml or pdf is to be created. Both should be created in the directory named in the environment variable %TEMP%. If write permissions are set and the error message continues to appear, it is possible that a pdf with the same name is already opened in Adobe Reader. If necessary, close any open pdf files.
5	(Birt Exception)	Please check the following: Do the users have full access + rights to change and delete folders on the directory drive path_of_birt-runtime-osgi-4_6_0\ReportEngine\configuration. (see here) Were the environment variables set correctly? (as described here) Does the directory C:\User\%Username%\AppData\Local\Temp already contain 1000 files of the type cx-report-xxx.pdf (xxx= 0-999)? If this is the case, delete these files. Write permissions in the BIRT Runtime directory are missing. Give the directory write permissions or copy it to a location with write permissions.
6	FileNotFoundException	Check if rptdesign really exists and if the folder "Mandantname" exists in the directory "C:\Mandantname\Birt" (see error code 99)
7	UnsupportedEncodingException	It is possible that the data-xml is incorrectly encoded (it should be utf-8). Check if there are control characters at the beginning. Open the xml in Eclipse from the directory C:\temp.
8	IO Exception
12		The BIRT-Server was started by the first ClassiX user with his user rights. If now another user wants to create a BIRT report as well, it is recognized that a BIRT Server is already running and the task is sent to him. In this case the BIRT-Server does not have the rights to access the user's temporary directory. This can be remedied by setting this variable: SET CX_PREVENT_BIRT_SERVER=TRUE This variable prevents the BIRT server from starting automatically, so that each user calls their own instant of BIRT.
99	Exception (e.g. with a zero-pointer exception)	Other errors; check the following: The name of the report must not contain /. In this case, the report is not created. The folder "Client name" must exist in the directory "C:\Mandantname\Birt", since the report is saved by the report designer in this directory. If the folder does not exist, the report cannot be created correctly. The error message in the debug console is then: "The system cannot find the specified path". If two different ClassiX applications are started at the same time and you want to print reports with both applications, an error message is displayed. The reason is that both ClassiX applications want to create the same pdf document. But this is not possible the second time, because such a document is already opened and used. For this reason the pdf must be closed first. If the variable CX_BIRT_DEBUG_CONSOLE is set and "Java.lang.NullPointerException in the startupEngine" appears in the console, this may be because the Runtime Engine used is incorrectly configured. It may have been copied from another computer, which is not possible because computer-specific files are created, which causes errors. It is best to completely delete the folder "birt-runtime-osgi-4_6_0" and reinstall it as explained here.
100	Unknown error java.lang.OutOfMemoryError: Java heap space	Set environment variables in the calling batch file: SET _JAVA_OPTIONS=-Xms512m -Xmx1024m
	The system cannot find the specified path	The folder "Client name" must exist in the directory "C:\Mandantname\Birt", since the report is saved by the report designer in this directory. If the folder does not exist, the report cannot be created correctly. The error message in the debug console is then: "the system cannot find the path you entered".
	Value specification in totals line is incorrect EUR 232,479,000,000. instead of EUR 2,324,79 or Description of the Y-axis of the Sequential Graph consists of several black columns (characters that are superimposed on each other to form black columns)	This behavior occurred in an English language operating system environment with German ClassiX Locale. In the runtime folder of BIRT (%BIRT_HOME%\ReportEngine\configuration\) the config.ini must be extended by the following entry osgi.nl=en_EN This sets the locale hard to German, so that the sum calculation is correct again or the Description column of the Sequential Graph is displayed correctly again.
		See solution for error 5: Full access to ReportEngine\configuration This message may appear if GESTIN has been installed in the Program Files folder. The folder rights must then be extended for the user: "Create folder" is needed to fix the actual error "Create Files" is useful so that log files can be written at all.
	A 0 KB PDF is created in REPORT_DATA. (Empty PDF, which a PDF reader cannot open) Is sometimes also output as "Internal error" with error code -1.	Java 1.8 -> See configuration of BIRT from 3.7.2 Java 9/10 -> uninstall Java and install a current Java 1.8 version (Java 9 and 10 are not supported) Folder under CX_REPORT_DATA available? Default: C:\temp

Error in the BIRT reports

Errors in the birth reports can become apparent at different times. It is best if the errors are detected while the report is being created (for example, when using the preview tab, for an explanation, see Editing Birt Reports). The following errors have occurred during the revision of reports and their resolution is documented (for a more detailed explanation of the errors, see this document)

Often a blank PDF is displayed if there is an error in the Bird Report. In order to find the reason for this, the report should be opened in BIRT-Eclipse (from ClassiX) and then tested via the preview (tab). There you will usually find a more detailed error message in a similar style as in the examples in the following table.

General procedure for fault investigation

1. Is an error message displayed in the PDF? Is a blank PDF printed?
2. More detailed error messages can always be found in the preview tab in BIRT-Eclipse (for an explanation, see Editing Birt Reports).
3. Check:
   1. Can a preview be created, or does an error message and a Java stack trace appear directly? Is a data type possibly set incorrectly? For example: It is to be checked by a string instead of a float whether a value is smaller or larger.
   2. A preview with a red error message is displayed. If a particular report object is mentioned in the error message
   3. ?
      1. table:
         1. Is a specific column displayed? For example "Column Binding "delivered.mlDescription"": Check in the property editor for the table whether the binding is set correctly / still exists, etc.
         2. Error with org.eclipse.datatools.connectivity.oda.OdaException: Table may not be able to access the data source. Check paths and environment variables
         3. Is a specific expression displayed? Search for this expression in the XML code of the report to determine the exact location of the error call. Important: Each report object has a number by which it can be uniquely identified.
      2. Number of an object: Is there a reference to an object with a specific number? Each report object has a unique number by which it can be identified

4. Is no error message displayed in the preview? Does a report object have a cross in the outline (usually bottom left)? This indicates that this report object is not working properly.
5. If an error cannot be directly assigned to a report object or the error message cannot be interpreted. It is best to remove the report objects individually (images, data bindings, grids, tables) and check each time whether the error still occurs. This allows you to identify certain objects

6. Error message	Solution	Solution
   Table table: Column Binding "delivered.mlDescription" has referred to a data set column "delivered.mlDescritpion" which does not exist.	Bindings of a table are not up to date	For example, if the name of a variable was changed within ClassiX (instead of delivered.mlDescription to delivered.new.mlDescription), Birt cannot find this variable in the data source. So the dataset must be edited and the new column added. However, any existing references in the table must then be changed. For example, it is possible that a column binding had a reference to delivered.mlDescription, or that a column binding itself is called delivered.mlDescription. To check this, click on the table and check the bindings in the property tab. If this is not done, the error message will appear.
   Table table: An exception occured during processing. Please see the following message for details: Cannot open the connection for the driver: org.eclipse.datatools.enablement.oda.xml	A data source is not available	This error message occurs if the data source specified in the data source tab does not exist. This error should not occur in the new version (recognizable by the fact that the xml files are stored in "C:\temp"), if the report is called from ClassiX, because a data source is generated automatically. To fix the error you have to check the data source in the data source tab. You should check if this file exists and if necessary specify another one. If the new data-source works can be tested via "Text Connection".
   A BIRT exception occurred. See next exception for more information. Invalid javascript expression pression	Error in the Javascript expression	It is possible that only the brackets are wrong in this case. If the error message does not directly show the incorrect script. It is best to search for a term from the error message (for example "currency2") in the xml source code (in the tab "XML Source").
   Table table: - A BIRT exception occurred. See next exception for more information. Can not convert the value of to Binary type. (Element ID:374)	Error in the type of a binding in the table (here with a picture)	Most likely, an element in the table has the wrong type and therefore cannot be used by BIRT. To check this, first open the Binding Tab of the table (Select Table > Properties Editor > Binding). The Data Type column may contain "Blob". In this case, an element used to display an image had the type "Blob". This had to be changed to "String".
   Table table: + Next data row cannot be retrieved org.eclipse.datatools.connectivity.oda.OdaException: The xml source file cannot be found or the URL is malformed. (Element ID:376)	BIRT cannot reach the data source	Probably the environment variable "CX_REPORT_DATA" was not set as environment variable in Windows, or the value of the Windows environment variable "CX_REPORT_DATA" does not correspond to the value environment variable in the calling batch file of ClassiX. Since both Eclipse and ClassiX access this environment variable, the environment variable must be defined as Windows environment variable.
   ClassCastException: "Error while executing the report".	Data type of the element incorrect	In the preview, the report is not displayed (not even empty), but a window is displayed in which this error message and Java stack trace are displayed. If you are asked if you want to "<0" oder ">0" ist so muss es als Float und nicht als String definiert werden. Dies muss im DataSet entsprechend angepasst werden.

   Hinweis
   Currently only version 4.6.0 (OSGI only) and 4.7 upwards (POJO only) are supported. If you have installed another version, you can uninstall it and then install version 4.6.0.

Call BIRT from the command line

The following parameters must be known:

path to the birt_interface.jar
BIRT_HOME (check in the command line: set birt_home)
XML file
BIRT Design
Target file name

java  -classpath "Pfad_zur_Birt_interface.jar/birt-interface.jar;%BIRT_HOME%/ReportEngine/lib/*" org.instantview.report.exec.ExecuteReportClient C:\Temp\invanaly-Sequenzialtest.xml Y:\classix\Evaluate\BIRT\invanaly-Sequenzialtest.rptdesign C:\Temp\Sequentialtest.pdf