IBM Rational ClearQuest Report Launcher

The IBM Rational ClearQuest Report Launcher is a web application that allows users to launch data-pull reports that are saved on a server file system. The simple launcher navigation interface is much like a download site that allows the user to click folder links to locate desired reports. Clicking a report web link causes the report to be launched on the server and rendered in the browser.

The report launcher includes adapters to support server invocation of BIRT reports and Crystal reports. The tool does not include a specific report engine, so the server runtime for the target reporting system must be separately installed on the same web server as the report launcher.

For a Crystal Reports runtime target, the Report Server for Crystal Reports must be installed and configured using the instructions in the ClearQuest Information Center. See https://publib.boulder.ibm.com/infocenter/cqhelp/v7r1m0/index.jsp?topic=/com.ibm.rational.clearquest.webadmin.doc/topics/c_rpt_rs4crystal_ovw.htm

For a BIRT server environment, follow the BIRT configuration instructions to install the BIRT server runtime.

1.1 Who should consider this solution?

Organizations that prefer a lightweight solution for launching data-pull server reports
Organizations that wish to run reports on platforms not supported by the Report Server for ClearQuest. See http://www-01.ibm.com/support/docview.wss?rs=0&uid=swg21294762 for ClearQuest platform information.
Organizations that require flexibility in choosing BIRT runtime version
Organizations that prefer to manage reports on the file system rather than utilizing the Jazz-based Derby repository required by the Report Server for ClearQuest
Organizations that want to host Crystal Reports data-pull reports on UNIX platforms. The Report Server for Crystal Reports is supported on UNIX , but current releases of ClearQuest do not provide an interface to launch Crystal data-pull reports on UNIX.

2 License

Before deploying the IBM Rational ClearQuest Report Launcher, please view the license agreement in the directory /ReportLauncher/license. Click here to open the English version of the license.

3 Deploying the ClearQuest Report Launcher

This section provides instructions for installing and configuring the report launcher on the WebSphere Application Server.

3.1 Installing the ClearQuest Report Launcher

The instructions in the sections that follow assume a WebSphere Application Server is already installed. Installation of ClearQuest server components automatically installs the WebSphere Application Server.

Unzip the cqrlauncher.zip archive to a temporary directory. This will create a base directory named ReportLauncher. After unzipping the archive, use the WebSphere Integrated Solutions Console to deploy the required web applications.

The report launcher download includes an enterprise archive file named cqreportlauncher.ear which must be deployed to the application server. Follow the steps below to use the WebSphere Integrated Solutions Console for installing the report launcher.

1. From a browser, access the web page: http://server_host:12060/ibm/console/login.do

2. Select Applications -> Enterprise Applications

3. Click Install button

4. From Preparing for the application installation page, click the Browse button and navigate to the directory where the report launcher is extracted.

5. Select the file cqreportlauncher.ear

6. Click the Next button

7. From Select installation options page, click Next

8. From Map modules to servers, select ClearQuest Report Launcher

9. Click Next

10. From Summary page click Finish

11. After successful deployment, click the Save link to save changes to the master configuration.

3.2 Configuring the ClearQuest Report Launcher

Configuration of the Report Launcher is customized using a configuration file named

reportlauncher.properties. From a command prompt, use the command below to navigate to the configuration directory.

Windows:

cd "%RATIONAL_COMMON%\CM\profiles\cmProfile\installedApps\dfltCell\RationalClearQuestReportLauncher.ear\CQReportLauncher.war\WEB-INF\classes

UNIX or Linux:

cd /opt/rational/common/CM/profiles/installedApps/dfltCell/RationalClearQuestReportLauncher.ear/CQReportLauncher.war/WEB-INF/classes

After navigating to the target directory, use the instructions below to update the report launcher configuration.

1. Using an editor, open the file reportlauncher.properties

2. Change the entry reports.launcher.baseDirectory to point to one or more base directories where reports are stored. The report launcher can navigate to the subdirectories of the base directory. Multiple base directory definitions are separated using a semicolon.

3. If you plan to use a BIRT version that is higher than 2.3.1, you must also enable the setting shown below:
reports.launcher.birt.reportPathPrefix=file:///

4. For most cases, the other configuration properties should not require modification. Read the comments in the reportlauncher.properties file to determine if additional property modifications are needed.

5. Save the updated reportlauncher.properties.

6. If the report launcher web application is started, it must be stopped and restarted to capture configuration changes.

4 Deploying the BIRT server runtime

The report launcher builds the appropriate URL to invoke a BIRT report; however, the BIRT runtime for report execution must be separately installed. This section provides the steps necessary for acquiring the BIRT runtime and installing on a WebSphere Application Server.

4.1 Choosing a BIRT runtime version

Report launcher verification was performed using BIRT versions 2.3.1, 2.3.2.2, and 2.5.1. Before deciding on a BIRT version, please view Known Problems and Limitations.

4.2 Downloading the BIRT runtime archive

Download the Runtime archive which is suitable for usage with Java/J2EE applications.

http://www.eclipse.org/birt/phoenix/

Extract the contents of the archive to a temporary directory.

4.3 Creating the BIRT enterprise archive (EAR) file

1. Copy the file birt.war from the BIRT runtime archive to the ReportLauncher/birt subdirectory of the extracted IBM Rational ClearQuest Report Launcher archive.

2. Open a Command Prompt, and navigate to the ReportLauncher/birt directory.

3. Create the BIRT enterprise archive file required for WebSphere installation. The instruction below creates a file named birt.ear that contains the birt.war server runtime.
jar -cvf birt.ear META-INF/* birt.war

NOTE: The “jar” command required for step #3 is only available for users that have a Java JDK installed on their system. If the “jar” command is not available on the target system, an alternative archive tool can be used to build the birt.ear. For example:

zip –r birt.ear ./META-INF/* birt.war

See http://wiki.eclipse.org/Birt_WebSphere_Deployment for additional information about creating the BIRT ear file.

4.4 Installing BIRT enterprise archive

This section describes the steps for deploying the BIRT enterprise archive file to the WebSphere Application Server.

1. From a browser, access the web page: http://server_host:12060/ibm/console/login.do

2. Select Applications -> Enterprise Applications

3. Click Install button

4. From Preparing for the application installation page, click the Browse button and navigate to the directory where the BIRT enterprise archive file was created.

5. Select the file birt.ear

6. Click the Next button

7. From Select installation options page, click Next

8. From Map modules to servers, select Eclipse BIRT Report Viewer

9. Click Next

10. From Map virtual hosts for Web modules page, select Eclipse BIRT Report Viewer, and click Next

11. From Summary page, review settings and click Finish

12. After successful deployment, click the Save link to save changes to the master configuration.

4.5 Configuring BIRT in WebSphere Application Server

After installing BIRT on the application server, several configuration settings must be changed. Follow the instructions below to complete the configuration.

1. From a web browser, navigate to the WebSphere Integrated Solutions Console URL http:// server_host:12060/ibm/console/login.do

2. Select Applications -> Enterprise Applications

3. Select the link labeled “BIRT Application”. This opens a Configuration tab to allow customization of BIRT settings.

4. From the Detail Properties section, select Class loading and update detection

5. For Polling interval for updated files, supply an integer value (ie. 60)

6. For Class loader order, select Classes loaded with application class loader first

7. For WAR class loader policy, select Single class loader for application

8. Click OK to save the updated settings

9. Click Save link to save the settings back to the master configuration

When using BIRT version 2.3.2 or higher, you must update the BIRT web.xml using the instructions below. See Known Problems and Limitations for information about this change.

1. Edit the BIRT web.xml file at the path below <profileName>/installedApps/dfltCell/birtEAR.ear/birt.war/WEB-INF/web.xml

2. Change the setting of the parameter WORKING_FOLDER_ACCESS_ONLY from true to false as shown below

<context-param>

<param-name>WORKING_FOLDER_ACCESS_ONLY</param-name>

<param-value>false</param-value>

</context-param>

3. Save the file

For additional information on BIRT deployment, see http://wiki.eclipse.org/BIRT/FAQ/Deployment.

4.6 Configuring the ClearQuest Reporting Driver

To run BIRT reports that require the ClearQuest Reporting Driver, you must copy the Eclipse plugins for the ClearQuest Reporting Driver to the appropriate directory of the BIRT web application. The plugins for the ClearQuest Reporting Driver are:

com.ibm.rational.clearquest.core.lib

com.ibm.rational.clearquest.jdbc

com.ibm.rational.clearquest.jdbc.nl1

com.ibm.rational.clearquest.oda.jdbc

com.ibm.rational.clearquest.oda.jdbc.nl1

com.ibm.rational.stp

If the Rational ClearQuest Client component is installed on the server machine, the required plugins can be copied from the shared Installation Manager directory:

Windows:

\Program Files\IBM\IMShared\plugins\

UNIX or Linux:

/opt/ibm/IMShared/plugins

Otherwise, the plugins can be downloaded from the /plugins directory of your Installation Manager repository.

The ClearQuest Reporting Driver plugins must be copied to the BIRT server directory shown below.

Windows:

\Program Files\IBM\RationalSDLC\common\CM\profiles\cmprofile\installedApps\<cell>\<BIRT ear>\birt.war\WEB-INF\platform\plugins

UNIX or Linux:

/opt/rational/common/CM/profiles/cmprofile/installedApps/dfltCell/<BIRT ear>/birt.war/WEB-INF/platforms/plugins

After the driver plugins are copied, restart the BIRT application to activate the changes. This can be done using the WebSphere Integrated Solutions Console (http://server_host:12060/ibm/console/login.do)

5 Deploying the Crystal Reports server runtime

The Crystal Reports adapter of the report launcher uses the ClearQuest Report Server for Crystal Reports as the launch target for data-pull reports created with Crystal Reports. Instructions for configuring the Report Server for Crystal Reports can be found at https://publib.boulder.ibm.com/infocenter/cqhelp/v7r1m0/topic/com.ibm.rational.clearquest.webadmin.doc/topics/t_rpt_rs4crystal_config.htm.

6 Using the ClearQuest Report Launcher

The report launcher is invoked from a web browser, using a URL of the form below:

http://server_host:12080/cqreportlauncher/ReportLauncherMain.jsp

The user interface for the report launcher is intentionally very lightweight and simple. The left navigation pane displays a collection of folders and reports available on the server file system. Clicking a folder link drills down into the selected folder, and clicking a report causes the report to be launched on the server and rendered in the right browser pane.

6.1 Providing credentials

The Set credentials link of the report launcher allows the user to specify credentials that are stored and passed when launching reports. When user credentials are saved, the name of the user is displayed in the upper left portion of the page. Use the Clear credentials link to remove the saved credentials.

Crystal Reports and BIRT both provide a mechanism for passing user credentials to be used during report execution. If no credentials are provided during report launch, Crystal Reports automatically prompts for the user credentials of the target data source. BIRT reports can also be designed to prompt for user credential information, but special steps must be completed when creating the report design. See BIRT report design considerations for information.

You can navigate directly to the report launcher credentials page using a URL like the one below.

http://server_host:12080/cqreportlauncher/ReportLauncherCredentials.jsp

6.2 Navigating directly to a subdirectory

For report launcher installations that include deeply nested subdirectories, you may wish to navigate directly to a specific path rather than drill down to the target subdirectory. This can be accomplished by specifying a dir parameter in the report launcher URL string. The value of the dir parameter is the relative path for the desired file location. For example:

http://server_host:12080/cqreportlauncher/ReportLauncherMain.jsp?dir=/Reports/Department1/Defect_Reports

7 BIRT report design considerations

Special steps are needed if you want to build BIRT reports that allow user credentials to be passed or entered at runtime. This section describes how to define ClearQuest data sources in BIRT that allow for user and password information to be passed as invocation parameters by the report launcher at runtime.

NOTE: Password information is not automatically encrypted when passing parameters to BIRT reports on the report server. It is strongly recommended that BIRT and the Report Launcher be deployed using a secure connection (https). Instructions for configuring secure sockets for ClearQuest web components can be found in the ClearQuest Information Center. See https://publib.boulder.ibm.com/infocenter/cqhelp/v7r1m0/index.jsp?topic=/com.ibm.rational.clearquest.webadmin.doc/topics/cm_server/t_config_cmserver_for_secure_sockets.htm

7.1 Passing credentials

To enable passing of credentials to a BIRT report, perform the following steps:

7.1.1 Create BIRT parameters for UserId and Password

1. Open the target report

2. Select the Data Explorer tab

3. Select Report Parameters

4. Right-click, and select New Parameter

5. Enter the name for the parameter (ie. “UserId”)

6. Customize the parameter as desired. Most settings effect how the parameter is displayed by the BIRT parameter prompter.

7. When finished, click OK

8. Repeat the steps above to define the “Password” parameter.

7.1.2 Update the ClearQuest Query Data Source to use parameters

1. Select the target ClearQuest data source

2. Right-click and select Edit

3. From the Edit Data Source dialog, select Property Binding

4. For User Name, click the button to the right of the text box

5. From Expression Builder Category list, select Report Parameters

6. From the Sub-Category list, select ---All---

7. Double-click the UserId item to create the parameter expression

8. Click OK to save the parameter retrieval code

9. For Password, click the button to the right of the text box

10. From Expression Builder Category list, select Report Parameters

11. From the Sub-Category list, select ---All---

12. Double-click the Password item to create the parameter expression

13. Click OK to save the parameter retrieval code

7.1.3 Verify report launcher parameter names

The names for the UserId and Password parameters can be changed in the BIRT report, but the values must match the settings in the report launcher configuration file. If your reports use different parameter names for the UserId and Password parameters, update the report launcher configuration file to specify the correct names for the properties below. See Configuring the ClearQuest Report Launcher.

reports.launcher.birt.userParameterName=UserId

reports.launcher.birt.passwordParameterName=Password

If the user and password parameter values are not saved in the report or passed by the report launcher, BIRT will prompt for the values prior to running the report.

7.1.4 Clear user and password settings

When creating a data source for a BIRT report, the BIRT report designer saves the user name and an encrypted representation of the password in the report design (rptdesign) file. If you want to require each user to specify their ClearQuest credentials at runtime, you must clear the user name and password settings in the report design before copying the report design file to the report launcher directory structure. To remove the credentials, do the following:

Open the target report in the BIRT report designer
Expand the BIRT Data Sources, and select the target ClearQuest data source
From the Properties viewer, clear the contents of the User Name and Password settings
Save the report design

7.1.5 Examples

The BIRT report samples included with the IBM Rational ClearQuest Eclipse client demonstrate parameterized user and password capability. The samples are in the directory below:

Windows:

\Program Files\IBM\IMShared\plugins\com.ibm.rational.clearquest.report.samples_7.x.x\BIRT

UNIX or Linux:

/opt/ibm/IMShared/plugins/com.ibm.rational.clearquest.report.samples_7.x.x/BIRT

The UserId and Password parameters are defined in a reusable BIRT report library called CQSamples.rptlibrary.

8 BIRT Report Viewer customizations

The generated launch URL for the BIRT Report Viewer can be customized by changing the reports.launcher.birt.serverPath setting in the reportlauncher.properties file.

For example, to suppress the display of the report viewer toolbar, update the setting as shown below:

reports.launcher.birt.serverPath=/birt/frameset?__report=%reportPath&__title=%title& __toolbar=false

For a description of other viewer settings, see http://www.eclipse.org/birt/phoenix/deploy/viewerUsage2.2.php

9 Sharing reports on the server

The ClearQuest Report Launcher does not provide a mechanism for uploading reports to the report server. However, report files can be shared using basic facilities that already exist in most organizations. This section offers a few simple ideas for surfacing report files that can be launched using the report launcher.

9.1 Shared drive

One simple way to make reports visible in the report launcher is to store report files on a shared drive that is accessible by the report launcher server and by client computers that are used to create and share reports. Access to the shared drive can be restricted using the built-in capabilities of the operating system.

9.2 File Transfer Protocol (FTP)

The File Transfer Protocol is another commonly available mechanism that can be used to transport report files from a client machine to the report launcher server. FTP server security is managed by the FTP software.

9.3 Source Configuration Management System

Report files that are accessible from the report launcher server machine can be made visible to the report launcher. Using a source configuration management (SCM) system like Rational ClearCase or CVS allows report designers to leverage the capabilities of the SCM system and store report design files under version control. Server administrators can use the SCM system to create directory views that are loaded from SCM streams. When updates are made to report files under source control, changed files can be refreshed on a report server by updating/synchronizing the SCM view on the server. This approach provides a simple mechanism for enabling multiple report servers to provide access to the same report files.

10 Network security

Report parameters and user credentials are not automatically encrypted when using the report launcher. It is strongly recommended that the report launcher be deployed using a secure connection (https). Instructions for configuring secure sockets for ClearQuest web components can be found in the ClearQuest Information Center. See https://publib.boulder.ibm.com/infocenter/cqhelp/v7r1m0/index.jsp?topic=/com.ibm.rational.clearquest.webadmin.doc/topics/cm_server/t_config_cmserver_for_secure_sockets.htm

11 Data security

The report launcher does not restrict visibility to report files that are hosted in a configured report launcher directory. A user with access to the report launcher server can browse the list of reports that exist in the report launcher directories for that server. However, in order to run a report that uses the ClearQuest Reporting Driver, the user must be authorized to run the ClearQuest queries used by the report. For example, if the user named ‘user’ attempts to run a report that requires access to a query in the Personal Queries folder of the user ‘admin’, an error like the one below occurs during report execution:

Cannot get the result set metadata. SQL statement does not return a ResultSet object. SQL error #1: CRVAP0237E Resource 'cq.query:Personal Queries/All Defects@7.0.0/SAMPL': not found.

ClearQuest access control capability can be used to restrict access to report data so that reports which consume restricted queries can only be run by those who have access to those queries.

12 Known problems and limitations

12.1 BIRT Version mismatch using Firefox 3.0

BIRT Report Viewer versions prior to version 2.3 may display a “Version mismatch” error for reports launched with a Firefox 3.0 browser. Information about this problem can be found at http://www.birt-exchange.org/forum/deploying-integrating-birt-report-engine-applications/11073-version-mismatch-firefox-3-a.html

12.2 Issues with BIRT drill through reports

There are some general issues with drill-through for BIRT 2.3.2.x and 2.5.x. See:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=282961

12.3 There is no report design object available

Error: “There is no report design object available” occurs when attempting to launch a report or drill through to a subreport using BIRT 2.3.2 or higher. For a discussion of this issue, see:

http://www.eclipse.org/forums/index.php?t=msg&goto=367339&S=164ca6c5cc1ce4c34abcf0e29c563893

Workaround/solution:

1. Edit the report launcher configuration file reportlauncher.properties

2. Verify the setting below is specified:
reports.launcher.birt.reportPathPrefix=file:///

3. Save the file

4. Edit the BIRT file <profileName>/installedApps/dfltCell/birtEAR.ear/birt.war/WEB-INF/web.xml

5. Change the setting of the parameter WORKING_FOLDER_ACCESS_ONLY from true to false as shown below

6. Save the file

7. Restart the server to activate the changes

<context-param>

<param-name>WORKING_FOLDER_ACCESS_ONLY</param-name>

<param-value>false</param-value>

</context-param>

12.4 Cannot find or process the com.ibm.rational.clearquest.oda.jdbc.dataSource

org.eclipse.birt.report.engine.api.EngineException: An exception occurred during processing. Please see the following message for details: Cannot find or process the com.ibm.rational.clearquest.oda.jdbc.dataSource driver's data source extension configuration. com.ibm.rational.clearquest.oda.jdbc.dataSource

The ClearQuest Reporting Driver is not properly deployed to the BIRT server runtime application. See Configuring the ClearQuest Reporting Driver for driver deployment information.

12.5 CRVAP0049E Cannot instantiate protocol provider: cqjniproxy (Not found in java.library.path)

This error occurs when two different web applications attempt to access ClearQuest using the JNI adapter of the Change Management API. For example, if both BIRT and the ClearQuest Report Server for Crystal Reports are deployed to the same web server, only one of the server applications can run reports that use a Change Management API JNI data source. This problem does not occur for reports that use a Change Management Server data source. See the IBM Rational ClearQuest Information Center for information about defining Change Management Server data sources.