You must place the BIRT report viewer in a location where Apache Tomcat can access it. Typically, this location is the $TOMCAT_INSTALL/webapps directory. On restarting Apache Tomcat, the application server automatically recognizes and starts the BIRT report viewer application if the BIRT report viewer is in this folder.

The BIRT report viewer files provide core functionality to run, render, and view BIRT reports. To use additional JDBC drivers that are not part of the standard BIRT packages, you must install these drivers as well as the BIRT report viewer itself. If you install the BIRT report viewer as a WAR file, you must include the JDBC drivers in the WAR file.

The following instructions assume that you have installed the BIRT Report Engine from the BIRT website, that your web application directory is $TOMCAT_INSTALL/webapps, and that your BIRT run-time installation directory is $BIRT_RUNTIME.

The steps to install the BIRT report viewer from the WAR file differ depending upon whether you need to include additional JDBC drivers for your reports. If there are no additional drivers, install the WAR file from the BIRT Report Engine installation. If you use additional JDBC drivers, you must pack them into the WAR file before you deploy it.

To install the BIRT report viewer as an application in a file system folder, use the WebViewerExample folder in the BIRT Report Engine installation.

To test the installation of the BIRT report viewer described in earlier sections, type the following URL in a web browser address field:

<server_name> is the name of the application server and <port> is the port that the application server uses.

Tomcat opens the JavaServer Page (JSP), index.jsp. This file exists in both the WAR file and in the BIRT report viewer root directory. A link on this page runs the simple BIRT report design file, test.rptdesign. If the BIRT report viewer is installed correctly, Tomcat uses index.jsp to process the report design and generate and render the report that it describes. The first time you run the report, Tomcat compiles the JSP files that comprise the viewer, so there is a delay before the report appears in the web browser.

If there are problems accessing the BIRT report viewer, use the Tomcat manager to verify that the BIRT report viewer is running on Apache Tomcat. Running the Tomcat manager requires a manager’s account. If a Tomcat manager account does not exist, create one by adding the following line to $TOMCAT_INSTALL/conf
/tomcat-users.xml:

Having a manager’s account available, first open the Tomcat main page, which for a typical Apache Tomcat installation is http://localhost:8080, as shown in Figure 4‑1.

On the Tomcat main page, choose Manager App. In the manager login window, type the user name and password of the manager account defined in the tomcat‑users.xml file. When the BIRT report viewer application is running, the Running status for Eclipse BIRT Report Viewer is true, as shown in Figure 4‑2.

By default, the context root of the URL for a web application is the path to the application directory or the WAR file. The default WAR file for the BIRT report viewer is birt.war, so the default URL to access a BIRT report from Apache Tomcat is similar to the following one:

To change the BIRT context root, change the name of the /birt directory or the WAR file in $TOMCAT_INSTALL/webapps. Next, restart Apache Tomcat. In the URL to access your BIRT report, specify the name that you chose. For example, if you chose reports, the URL to access a BIRT report becomes:

The URL examples in this section use a relative path to access the report design. The BIRT_VIEWER_WORKING_FOLDER parameter sets the path to access a report design as a relative path.

To place the BIRT report viewer in a location other than $TOMCAT_INSTALL
/webapps, add a context mapping entry to the server.xml file in $TOMCAT_INSTALL/conf by adding the following line to server.xml just above the </host> tag near the end of the file:

birt_context is the context root for the BIRT report viewer application. BIRT_Path is the absolute path to the BIRT report viewer directory.

Save the changes to server.xml and restart Apache Tomcat to make the changes active.

BIRT Report Engine requires certain TrueType fonts to display a PDF report. BIRT searches for fonts in the common font directories for Windows and Linux. The directories that BIRT searches on a Windows system include:

and on a Linux system include:

If PDF reports appear to be missing content, place the necessary fonts in any of the directories in the preceding list. Alternatively, specify your own font search path in the environment variable BIRT_FONT_PATH.

To determine the locations for report designs, images in reports, and log files, the BIRT report viewer uses context parameters defined in the web.xml file. The path provided as the value for any of these parameters can be relative or absolute. A relative path is relative to the root folder of the BIRT report viewer application. A path to a writable location for a BIRT report viewer that is deployed as a WAR file must be an absolute path.

By default, the relative path for report designs is relative to the BIRT report viewer’s root folder. Place all report designs in this folder or use the full path to the report design in the URL. Using a relative path is not convenient for deployment of the BIRT report viewer in a WAR file as changes to report designs would require repackaging the WAR file. To set a different location for report designs, change the BIRT_VIEWER_WORKING_FOLDER parameter in the BIRT report viewer application’s web.xml file.

Other context parameters determine other aspects of the behavior of the BIRT report viewer, such as the default locale and the level of detail in the log files.