IBM Rational ClearQuest Report Exporter

 

 

IBM Rational ClearQuest Report Exporter 1

Introduction. 1

Licensing. 1

Installation. 1

Usage. 3

Report Exporter parameters. 3

Example output 4

Unshared resources. 5

BIRT report credentials. 5

Using parameterizeCredentials for reports on the file system.. 5

Usage. 6

Troubleshooting. 6

Capturing debug information. 6

Frequently asked questions. 7

Introduction

The IBM® Rational® ClearQuest® Report Exporter is a command line tool that extracts all report files from the Report Server for ClearQuest repository and saves the files to the local file system. Once the report files are saved to the file system, the reports can be launched from a web browser using the Report Launcher for ClearQuest web application.

Licensing

View the license agreement in the directory /reportExporter/license before using the IBM Rational ClearQuest Report Exporter. 

Installation

Download the IBM Rational ClearQuest Report Exporter archive. Then, follow these instructions to install the archive. The instructions assume that you are logged on to the server machine where the Report Server for ClearQuest is installed.

 

  1. Copy the reportExporter_<id>.zip archive to the following directory:

 

Windows:

C:\Program Files\IBM\RationalSDLC\ClearQuest\RCQR

 

Linux:

/opt/rational/clearquest/RCQR

 

  1. From a command prompt, navigate to the archive directory path, and then extract the archive contents using the following command:

 

Windows:

"%RATIONAL_COMMON%/infozip/unzip" reportExporter_<id>.zip

 

Note: The program used file in the previous command to extract the archive is not installed with all IBM Rational ClearQuest features. If the program is not on your file system, use an alternative archive extraction program to store the archive contents on the file system.

 

Linux:

unzip reportExporter_<id>.zip

 

Extracting the file creates a subdirectory called ./reportExporter that contains the following files:

 

File name

Description

parameterizeCredentials.bat

Command file to launch a tool that parameterizes ClearQuest user credentials for BIRT reports on Windows.

 

parameterizeCredentials.sh

Shell script to launch a tool that parameterizes ClearQuest user credentials for BIRT reports on Windows

 

parameterizeCredentials _log4j.properties

Log configuration file to specify log4j options for the parameterizeCredentials tool

.

reportExporter.bat

Command file to launch the report exporter on Windows.

 

reportExporter.sh

Shell script to launch the report exporter on Linux.

 

reportExporter_log4j.properties

Log configuration file to specify log4j options.

 

 

  1. After extracting the archive, Linux users must set the required file permission on reportExporter.sh and parameterizeCredentials.sh to permit execution of the shell script. From a Linux shell, navigate to the ./server subdirectory, and run the following command:


Linux:

chmod u+x reportExporter.sh

chmod u+x parameterizeCredentials.sh

 

 

Usage

Note: Shut down the Report Server for ClearQuest before running the report exporter.

 

This section demonstrates the command syntax used to run the IBM Rational ClearQuest Report Exporter. These instructions assume that you are logged on to the server machine where the Report Server for ClearQuest is installed. Open a command prompt and follow these instructions:

 

Windows:

  1. Navigate to C:\Program Files\
    IBM\RationalSDLC\ClearQuest\RCQR\reportExporter
    .
  2. Run the following command:
    reportExporter -username <id> -password <pw> -basePath <filePath> -removeCredentials (true|false) –parameterizeCredentials (true|false)

 

Linux:

  1. Navigate to /opt/rational/clearquest/RCQR/reportExporter.
  2. Run the following command:
    ./reportExporter.sh -username <id> -password <pw> -basePath <filePath> -removeCredentials (true|false) –parameterizeCredentials(true|false)

Report Exporter parameters

The following parameters can be used when invoking the report exporter.

 

 

 


Example output

Command:

reportExporter –username admin –password adminpw –basePath c:/reportalExport

 

INFO  - Export report designs to file system

INFO  - Loading configuration from "file:C:\Program Files\IBM\RationalSDLC\ClearQuest\RCQR\server\teamserver.properties".

INFO  - Initial database connection successful

  Db Product Name: Apache Derby

  Db Product Version: 10.3.2.2 - (650004)

  Db Name/Location: C:/Program Files/IBM/RationalSDLC/ClearQuest/RCQR/server/repositoryDB

ERROR  - CRJAZ1054I Invalid ChangeEvent expiration itemType specification com.ibm.team.workitem.WorkItem:com.ibm.team.workitem.WorkItem:5184000 com.ibm.team.build.BuildResult:172800.

ERROR  - CRJAZ1054I Invalid ChangeEvent expiration itemType specification com.ibm.team.build.BuildResult:com.ibm.team.workitem.WorkItem:5184000 com.ibm.team.build.BuildResult:172800.

INFO  - Authenticating user "admin"

INFO  - Creating new directory "c:/reportalExport"

INFO  - Start export for folder "JNI"  (owner=admin  shared=true)

INFO  -   Creating new directory "c:/reportalExport/JNI"

INFO  -   Start export for report "Defect Summary (JNI)" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/JNI/cqbanner.JPG"

INFO  -     Saving "c:/reportalExport/JNI/DefectsSummary_JNI.rptdesign"

INFO  -   End export for report "Defect Summary (JNI)"

INFO  -   Start export for report "Defect By State (JNI)" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/JNI/DefectsByState_JNI.rptdesign"

INFO  -   End export for report "Defect By State (JNI)"

INFO  - End export for folder "JNI"

INFO  - Start export for folder "CM"  (owner=admin  shared=true)

INFO  -   Creating new directory "c:/reportalExport/CM"

INFO  -   Start export for report "Defect Summary (CM)" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/CM/cqbanner.JPG"

INFO  -     Saving "c:/reportalExport/CM/DefectsSummary_CM.rptdesign"

INFO  -   End export for report "Defect Summary (CM)"

INFO  -   Start export for report "Defect By State (CM)" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/CM/DefectsByState_CM.rptdesign"

INFO  -   End export for report "Defect By State (CM)"

INFO  - End export for folder "CM"

INFO  - Start export for folder "XMLDriverTest"  (owner=admin  shared=true)

INFO  -   Creating new directory "c:/reportalExport/XMLDriverTest"

INFO  -   Start export for report "XMLDriverTest" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/XMLDriverTest/XMLDriverTestReport.rptdesign"

INFO  -     Saving "c:/reportalExport/XMLDriverTest/ReportTest.xml"

INFO  -   End export for report "XMLDriverTest"

INFO  -   Start export for report "ReportWithIntegerNull" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/XMLDriverTest/ReportWithNullInteger.rptdesign"

INFO  -   End export for report "ReportWithIntegerNull"

INFO  - End export for folder "XMLDriverTest"

INFO  - Start export for folder "APARFixes"  (owner=admin  shared=true)

INFO  -   Creating new directory "c:/reportalExport/APARFixes"

INFO  -   Start export for report "ReportWithNull" (owner=admin  shared=true)

INFO  -     Saving "c:/reportalExport/APARFixes/ReportWithNullInteger.rptdesign"

INFO  -   End export for report "ReportWithNull"

INFO  - End export for folder "APARFixes"

INFO  - Export completed successfully

 

Unshared resources

Reports and folders that are saved in the Report Server for ClearQuest repository as unshared resources are exported to a subdirectory named unshared/<owner>. The folder structure for the resource is preserved. For example, if user “engineer” created an unshared report named “Report1” in folder “TeamReports/test”, the associated report resource file named “Report1.rptdesign“ is exported to:

<exportDirectory>/unshared/engineer/TeamReports/test/
Report1.rptdesign

BIRT report credentials

By default, the BIRT reporting engine connects to ClearQuest data sources using the credentials that were saved in the report during report design. If you want BIRT reports to prompt for user credentials or use the credentials passed by the Report Launcher for ClearQuest, you must design the reports to treat data source credentials as BIRT parameters. See the ClearQuest Information Center for information about designing BIRT reports that prompt for data source credentials. The Report Exporter has an optional parameter named parameterizeCredentials that automatically adds the required credential parameters during export. The parameterizeCredentials utility can also be run separately to modify BIRT reports that are already saved to the file system.   

Using parameterizeCredentials for reports on the file system

The report exporter includes scripts that parameterize ClearQuest credential fields for BIRT reports that are already saved on the file system.

 

Usage

This section demonstrates the command syntax used to run the parameterizeCredentials utility that is bundled with the IBM Rational ClearQuest Report Exporter. Open a command prompt and follow these instructions:

 

Windows:

  1. Navigate to the directory where the report exporter is extracted, for example:

C:\Program Files\IBM\RationalSDLC\ClearQuest\RCQR\
reportExporter

 

  1. Run the following command:
    parameterizeCredentials -inputPath <filePath_1> -outputPath <filePath_2>

 

 

Linux:

  1. Navigate to the directory where the report exporter is extracted, for example: /opt/rational/clearquest/RCQR/reportExporter

 

  1. Run the following command:
    ./parameterizeCredentials.sh -inputPath <filePath_1> -outputPath <filePath_2>

 

Note: The outputPath argument is optional. If outputPath is not specified, report files are replaced in the inputPath.

Troubleshooting

This section provided information to help diagnose and correct problems that occur while running the IBM Rational ClearQuest Report Exporter.

Capturing debug information

The output of the report exporter is controlled using a log configuration file named reportExporter_log4j.properties. The default logging configuration writes informational messages from the report exporter, and outputs error messages that are logged. If problems occur and additional debug information is needed, Make the following change to reportExporter_log4j.properties to log more details:

 

Original property:

Changed property

log4j.rootLogger=ERROR, stdout

log4j.rootLogger=DEBUG, stdout

 

After making the change, rerun the reportExporter command file to activate the more granular logging.

 

Frequently asked questions

Q: The Report Server for ClearQuest has been uninstalled. Can I use the IBM Rational ClearQuest Report Exporter to export report files from a backup version of the repository?

 

A: Yes. The IBM Installation Manager preserves the Report Server for ClearQuest repository during update and uninstall operations. The repository is stored in the following default locations:

 

Windows:

C:\Documents and Settings\All Users\Application Data\
IBM\Rational.preserve\RCQR\repositoryDB

 

Linux:

/tmp/Rational.preserve/RCQR/repositoryDB

 

To export reports from the backed up repository to the file system, perform the following steps:

  1. Extract reportExporter_<id>.zip to a temporary directory.
  2. Copy the following launch files to the report exporter \server directory:
    \reportExporter\launch\reportserver.properties
    \reportExporter\launch\teamserver.properties
  3. Edit reportserver.properties to verify and update the ClearQuest user registry information for the Report Server for ClearQuest.
  4. Edit teamserver.properties. Update com.ibm.team.repository.db.jdbc.location with the location of the backed up repositoryDB. Use forward slashes to represent file path separators, for example:
    com.ibm.team.repository.db.jdbc.location=
    C:/Documents and Settings/All Users/Application Data/
    IBM/Rational.preserve/RCQR/repositoryDB
  5. Follow the instructions in the Usage section to run the ClearQuest Report Exporter.

 

Q: We have different versions of the same report saved in the same folder. How does the report exporter handle this case? 

 

A: When the report exporter detects that a file resource is already saved in the target directory, the new resource to be saved is assigned a unique name by prepending a numeric identifier. For example, if the report exporter tries to save a file named reportImage.gif and it detects that the file already exists, the new resource is saved as 1_reportImage.gif. A suitable message is logged to report this action.