IBM Rational
ClearQuest Crystal Reports Migration Tool
Installing and starting the migration tool
Downloading and configuring the Crystal Reports Java
Reporting Component
Upgrading saved report formats
Migrating reports that use mapped fields
Configuring the ClearQuest Reporting Driver
Navigating the migration tool wizard
Select Crystal Report for migration
Crystal Reports Migration Result
Known problems and limitations
Migrating reports with warning messages
Customizing dynamic filter parameters
Rational ClearQuest Product Release Notes
Beginning in
Releases prior to Rational ClearQuest 7.1 support a “data-push” model of reporting in which a ClearQuest client executes a query and invokes Crystal Reports to format the output using a report format that is saved in the ClearQuest repository. The new model introduced in Rational ClearQuest 7.1 is a “data-pull” model that allows the reporting system to connect to ClearQuest databases using the ClearQuest Reporting Driver as a data source to retrieve query results that populate reports.
Using Crystal Reports and the ClearQuest Reporting Driver, new data-pull reports can be created from scratch. Users with existing data-push reports can use the Crystal Reports Migration Tool to assist with conversion of those reports to use the data-pull model.
The following software components are required for migrating reports with the Crystal Reports Migration Tool.
Java Runtime Environment (JRE) 1.5 or
higher. The JRE included with
the Rational ClearQuest Client is used by
default. If the Rational ClearQuest Client is not installed on your machine, you can
download an
Using the data-pull reporting model, all information required for report execution is stored with the report format file, allowing the report to be executed without launching a ClearQuest client. You can use the Crystal Reports Migration Tool to perform the following general tasks to convert data-push reports to the data-pull model:
· Extract the Crystal Reports format file from the ClearQuest repository and save to the file system
· Create and save a ClearQuest query that returns all fields required by the Crystal Reports report format.
· Create a connection URL that allows Crystal Reports to connect to the ClearQuest Reporting driver
· Change the data source of the report format file to use the query created by the migration tool. Crystal Reports treats the saved ClearQuest query as a JDBC stored procedure.
· (Optional) Create an HTML file that can be used to launch the migrated reports using the Report Server for Crystal Reports feature of Rational ClearQuest..
The migration tool saves a new version of each report to the file system. Reports and report formats saved in the ClearQuest repository are not changed.
You might be able to simplify the report migration by completing the processes described in this section that are applicable in your environment
The Crystal Report Migration Tool is available as an archive (CRMT-<id>.zip) which can be downloaded and extracted to the file system on the machine where the migration tool will run before starting the migration process. You must also install and configure the required Crystal Reports Java Reporting Component before you begin the migration.
Before starting the Crystal Reports Migration Tool, you must first configure the runtime files from the Crystal Reports Java Reporting Component. To download the JRC, complete the following steps:
After downloading the JRC archive, you must run a configuration script to copy required JRC runtime files to the location required by the Crystal Reports Migration Tool. To run the configuration script, complete the following steps:
By default, the configureJRC.bat
script uses an archive extraction program that gets installed to the file path %RATIONAL_COMMON%/infozip/unzip during installation of ClearQuest
server components. If the unzip program
is not present on the file system prior to running configureJRC,
the following message displays:
“The system cannot find the path specified.”
If you do not have unzip.exe installed on your system, you can copy it from the following Rational ClearQuest Installation Manager repository path and extract to the file system.
<repository
base>/native/infozip_7.1.1000.0000-7-1-1-D091027.zip
If unzip.exe is installed on your system, complete the following steps to update configureJRC.bat.
When migrating reports that use
1. Install the Rational ClearQuest client for Windows.
2. Install Crystal Reports version 11
3. Open the ClearQuest client for Windows.
4. Select a report format that requires upgrade, right-click, and click Edit…
5. To open the Crystal Reports report designer, from the Edit Report Format dialog, click Author Report.
6. To refresh the report, press F5 .
7. The
Verify Database dialog opens with the message:
The database file “<file name>” has changed. Proceeding to fix up report!
8. Click OK.
9. The
Verify Database dialog again displays with the message:
The database is now up to date
10. To exit Crystal Reports, select File->Exit .
The Crystal Reports dialog opens to
warn that you are about to overwrite the Crystal Reports file with a newer
version. The warning may include a note
that the updated report format will not be editable from versions of Crystal Reports prior to version 9.
11. To save the updated report format, click Yes .
12. To save the updated report format to the ClearQuest database, from the ClearQuest Edit Report Format dialog, click OK .
13. Repeat steps 4-12 for other report formats that are used by the reports you want to migrate.
If a database field name is changed in the ClearQuest schema, Crystal Reports data-push reports that reference the old database field name are not resolved at runtime by the Report Server for Crystal Reports. This issue is described in tech note http://www.ibm.com/support/docview.wss?uid=swg21419660
The issue also occurs when using the Crystal Reports Migration Tool, and either solution from technote 1419660 can be used to resolve the problem. Option 2 from the technote involves modifying a server configuration file named crconfiguration.properties. To apply the mappings from crconfiguration.properties during migration, copy the file to the \crmt directory before launching the migration tool. Failure to apply the required mappings during migration results in a generated ClearQuest report query that does not include the mapped fields. If necessary, the migration tool can be rerun after defining appropriate mapping rules in crconfiguration.properties.
After migrating ClearQuest reports
to the data-pull model, report modification requires that the ClearQuest Reporting Driver be configured for usage with
Crystal Reports. See the
After completing the steps in the Preparing for the migration section, the Crystal Reports Migration Tool can be started from the Windows Explorer.
The migration tool wizard allows the user to provide information about the reports to be migrated. This section describes the pages of the Crystal Reports Migration Tool wizard.
This wizard page provides
information about the ClearQuest connection used for
migrating re-ports and captures values required for using the connection.
My Default ClearQuest Connections: Lists connection profiles defined on the local machine.
Change Management Server: A URL for a ClearQuest CM Server where the target ClearQuest connection profile is defined. For example:
http://myhost:12080/TeamWeb/services/Team
User Name: The ClearQuest user name for the user that performs the migration.
Password: The password for the ClearQuest user that performs the migration.
Schema Repository: The ClearQuest schema repository where target reports are stored.
Database: The ClearQuest database name where target reports are stored. This setting is represented as a combo box in the user interface. The names for accessible production databases can be selected from a list. Test database names are not displayed in the list and must be typed into the edit box.
This wizard page allows the user to select reports and
migration settings for migrating reports to the data-pull model.
Add All: Add all reports from all visible folders to the list of reports to be migrated.
Add: Add the selected report to the list of reports to be migrated.
Remove: Remove the selected report from the list of reports to be migrated.
Remove All: Remove all reports from the list of reports to be migrated.
Extract report format only: Save the targeted reports to the local file system, but do not attempt to migrate the connection information. Saved report format files can be manually migrated using the steps described in the Completing the migration section.
Preserve folder structure: Save
the ClearQuest folder structure to the file system
during migration. This option is checked
by default. Remove this check box if you
want to migrate report files to a single directory
using the ClearQuest database identifier to construct
unique report file names.
This wizard page allows the user to select the ClearQuest folder where report queries will be saved. The selected folder must be visible to all users who will run the reports, so the folder should be a subfolder of the Public Queries folder.
Create Folder: Create a new ClearQuest folder. The new folder will be a child of the currently selected folder from the folder viewer.
This wizard page allows the user to specify the file path on the local file system where report format files are saved during migration.
After specifying a valid file path, click Finish to perform the migration.
This wizard page opens after the migration tool finishes. The page displays the results of each migrated report. For report migrations with results other than “Success”, double-click the target report to view detailed information about the migration warning or failure. The migration tool provides recommended steps for completing the migration of reports that resulted in “Warning” messages.
The migrated reports are saved to the local directory specified by the user. The naming convention for the saved file closely resembles the saved name of the report in the ClearQuest repository.
This section can be used to generate an HTML page for launching migrated reports. In order to use this option, the migrated report files must reside in a directory path that is accessible by the Report Server for Crystal Reports. Therefore, the Report Server for Crystal Reports must be installed on the same machine where the migration is performed, or the migrated report format files must be stored on a shared drive that is accessible to the Report Server for Crystal Reports. The generated HTML files are stored in the folder that was specified in the Set local folder migration step. The HTML file named left.html contains the launch links for the migrated report, and that HTML file can be modified if the migrated reports are moved to a different location.
Run Reports: Click this button to launch
a browser that opens a test HTML page.
Include Password: Select this option to include an encrypted password for each of the report launch links in the test HTML page. If the password is not included, Crystal Reports will prompt for the username and password combination when a report is launched from the test page. Be mindful of your organization’s security practices when using this option.
· Report formats to be migrated must be saved using Crystal Reports version 9.0 or higher. Performing the steps from Preparing for the migration ensures that report formats are upgraded to a supported version before the migration is performed.
· If the a report cannot be migrated successfully, the Crystal Reports Migration tool generates an error or warning on the migration result wizard page. You can double-click on a report with a warning status for information about completing the migra-tion. For details, see Migrating reports with warning messages.
· The Crystal Reports Migration Tool detects and migrates only those reports that are visible to the user who runs the tool. For example, the user named Administrator cannot migrate reports saved in the Personal Queries folder of the user named User_1. Copying reports, report formats, and report queries to be migrated to a Public Queries subfolder prior to running the Crystal Reports Migration Tool allows all authenticated users to migrate those reports.
· The Crystal Reports Migration Tool logs migration error information to a file named crmt.log.
After the migration tool wizard process completes, additional work might be necessary to complete the migration. Migrating reports with warning messages provides information about using the Crystal Reports Designer to complete the report migration for reports that generated warning messages in the Crystal Reports Reporting tool. Migrating reports manually provides information about using the Crystal Reports Designer facilities to manually migrate reports.
.
In cases where migration cannot complete, the migration tool displays an error or warning for the report in the Crystal Reports Migration Result wizard page. You can double-click reports that issue “Warning” results to view instructions for completing the migration of the report.
Typical instructions for migration completion:
If necessary, migration of Crystal Reports to the data-pull format can be done manually using the facilities available in the Crystal Reports report designer.
a. To open the Database Expert, click Database->Database Expert
b. To open the JDBC(JNDI) connection dialog, click Create New Connection->JDBC (JNDI)->Make New Connection
c. Specify the settings for the ClearQuest Reporting Driver:
§ Connection URL: jdbc:cq:<dbset>/<database>[@<cm_server_url>]
Example: jdbc:cq:8.0.0/SAMPL@http://myhost:12080/TeamWeb/services/Team
The cm_server_url is optional. It is used for specifying connections to database profiles that are hosted on a change management server.
§ Database Classname: com.ibm.rational.clearquest.jdbc.CQDriver
§ To advance to the Connection Information page, click Next.
§ Enter User ID and Password.
d. To save the new connection, click Finish.
e.
To close the Database
Expert dialog, click OK.
After updating the data source, click F5 to refresh the report data for the report.
Reports that use dynamic query filters require special attention when creating data-pull reports. For ClearQuest queries, dynamic filters require that both an operator and an operand be specified. In Crystal Reports, the filter values are represented by parameter fields. The ClearQuest Reporting driver appends the suffix “_Operator” to the parameter field that stores filter operators and the suffix “_Parameter” to the parameter field that stores the filter values.
Valid query filter operators are listed below:
IS_EQUAL
IS_GREATER_THAN
IS_GREATER_THAN_OR_EQUAL
IS_IN_SET
IS_LESS_THAN
IS_LESS_THAN_OR_EQUAL
IS_NOT_BETWEEN
IS_NOT_EQUAL
IS_NOT_IN_SET
IS_NOT_NULL
IS_NULL
Crystal Reports
provides a variety of options for parameter fields to improve the usability of
your data-pull reports. See the Crystal
Reports Online Help for information about parameter fields.
The Crystal Reports Migration Tool uses the Rational ClearQuest 7.1.1.08 Change Management
CRVSV1014E Client is too new to use this server. Maximum version accepted: <version>
If the message appears in crmt.log, you should replace the CM libraries with the ones in your installation. Instructions for updating the CM libraries from your ClearQuest installation are provided below.
copy "%CLEARQUEST_HOME%\cqjni.jar"
.
copy "%CLEARQUEST_HOME%\stpcq.jar"
.
copy "%RATIONAL_COMMON%\stp*.jar"
.
For information about known problems and limitations in the Rational ClearQuest 7.1 product, see http://www.ibm.com/support/search.wss?&q=clearquest+RN7.1
For information about known problems and limitations in the Rational ClearQuest 8.0 product, see http://www.ibm.com/support/search.wss?&q=clearquest+RN8.0