How to use and administer the Report Server

Technote (FAQ)


Question

How do you use and administer the Report Server for IBM Rational ClearQuest?

Cause

The Report Server for ClearQuest user documentation is not in the ClearQuest Information Center for releases prior to 7.1.2.2.

Answer

Report Server for ClearQuest

Contents

Software requirements
Overview of the Report Server for ClearQuest

Administering the Report Server for ClearQuest Using the Report Server for ClearQuest Working with sample reports
Performance enhancements
Troubleshooting

Software requirements

Before you install the product, verify that your system meets the software requirements.

Browsers

The following browsers are supported by this product:

  • Microsoft Internet Explorer 7
  • Mozilla Firefox 2.0.0.9 and later

Server operating systems

The following server operating systems are supported by this product:

  • Windows 2003 (with Service Pack 2)
  • Red Hat Enterprise Linux 5 Update 1
  • SUSE Linux Enterprise Server 10 Service Pack 2

Application servers

WebSphere Application Server 6.1, with IBM Java SDK 1.5 SR5 or later cumulative fix applied, is supported by this product. WebSphere Application Server is installed when you install the WAN Support Packages for Rational ClearQuest.


Overview of the Report Server for ClearQuest

The Report Server for ClearQuest is a server component that supports the management and execution of reports produced with the data-pull model. You can use the Report Server for ClearQuest to manage, share, and run reports designed with BIRT or with Crystal Reports.

Rational ClearQuest reports can be designed with Crystal Reports or with the open-source BIRT designer included with the Rational ClearQuest Client for Eclipse. The Report Server for ClearQuest provides services to manage and run these reports. Report management services include basic management of user accounts, access control for reports, and folder creation and management. Report running services include running reports, printing reports, creating report snapshots, and exporting reports to PDF and Microsoft Word format.

You can access the Report Server for ClearQuest from the Rational ClearQuest Client for Eclipse, Rational ClearQuest Web client, or directly from a Web browser. ClearQuest MultiSite replication of report server sites is not supported. For more information, see the topic "Planning a deployment for the Report Server for ClearQuest" in the IBM Rational ClearQuest Information Center. Note that if you choose to deploy multiple instances of the Report Server for ClearQuest, each instance is independent and the data stored in the one instance is not propagated to the other instances.


Report Server workflow

The following figure illustrates the general workflow for using the Report Server for ClearQuest.

Diagram showing the workflow for Report Server for ClearQuest tasks. Security information is controlled and stored in the ClearQuest database. Report designs are stored in a local file system and uploaded to the Report Server for ClearQuest. Report instances and file structures are also stored in the Derby database.

  • When you log on to the Report Server for ClearQuest, your credentials are verified by the Rational ClearQuest security database. Permission for accessing, running, and sharing reports is determined by the permissions associated with your Rational ClearQuest account.
  • You can upload report designs from your local file system to the Report Server for ClearQuest. You can also work with a report previously stored in the local database of the Report Server for ClearQuest.
  • You can specify which users have permission to share reports. Shared reports are can be seen by all Report Server for ClearQuest users.
  • You can run a query against one or more Rational ClearQuest data sources.

Once a report is created, you can:
  • Store reports in the local Derby database
  • Organize reports into folders
  • Share reports with others
  • Export reports to a PDF or Microsoft Word format




User privileges

There are three levels of user privileges for the Report Server for ClearQuest:

  • Administrators: All Rational ClearQuest users with Super User privileges are administrators.
  • Leads: All Rational ClearQuest users with Public Folder Administrator privileges are leads.
  • Normal users: Any other Rational ClearQuest users are normal users.

The privileges associated with these user roles are:

Privilege Administrators Leads All users
Report and user administration
  • Grant and deny access to users
  • Manage uploaded reports
Yes No No
Share report folders Yes Yes No
Upload reports to owned report folders Yes Yes Yes
Share or unshare owned reports Yes Yes Yes
Execute a report Yes Yes Yes
Print, email, and export reports Yes Yes Yes

The Rational ClearQuest Super User or Public Folder Administrator privilege is granted with the Rational ClearQuest User Administrator tool. Consult your Rational ClearQuest administrator if you require that this privilege be added to your account.


Report Types

The Report Server for ClearQuest supports BIRT and Crystal reports.

BIRT reports are available in three forms:

  • Report designs: Report designs are templates with predetermined data sources and output formats. Report designs can have input parameters. When report designs are executed, users are prompted for the values of the parameters.
  • Report queries: Report queries are report designs with saved input-parameter values. When report queries are executed, users are not prompted for the parameter values. The queries run with the saved parameter values.
  • Report snapshots: Report snapshots are saved representations of formatted report output. The reports generated from report designs or report queries can be saved as report snapshots.

Crystal Reports reports are displayed through the Crystal Reports Viewer. The standard functionality of the Crystal Reports Viewer can be used. To be able to use Crystal Reports reports, ensure that Crystal Reports is installed on the same machine as the Rational ClearQuest server.


Security

Security for report viewing, generation, and management is provided by user authentication through a Rational ClearQuest database. When the Report Server is configured, the server administrator updates a configuration file to include connection information for the Rational ClearQuest database used for user credential validation. All user validation is performed through the Rational ClearQuest API.

The level of access control provided for the Report Server for ClearQuest is a subset of that available for Rational ClearQuest. Access control for the Report Server for ClearQuest is used to:

  • Determine the pool of eligible users for the Report Server administrator. Users of Report Servers must have existing Rational ClearQuest accounts before they can be granted access by the Report Server administrator.
  • Validate the user credentials during logon to the Report Server.
  • Determine which users have permission to share reports. Shared reports can be seen by all Report Server users.




Administering the Report Server for ClearQuest

Administrative tasks include managing users and reports.

Information on deploying and configuring the Report Server for ClearQuest is available in Rational ClearQuest documentation for administration of the Rational ClearQuest Web server. In addition to the procedures described there, some administrative tasks are done from the Report Server for ClearQuest. These include granting user access to the Report Sever and backing up the Apache Derby database that stores reports and report structures for the Report Server.

Users must have an existing Rational ClearQuest account before they can be added as users of the Report Server for ClearQuest.


Granting access to new users

To grant access to a group of users:

  1. Log in as administrator to the Report Server for ClearQuest.
  2. On the Administration panel on the left, click Users.
  3. To display the Add Users screen, click the plus icon.
  4. Select All users and click OK.




Granting access to selected users

To grant access to selected users:

  1. Log in as administrator to the Report Server for ClearQuest.
  2. On the Administration panel on the left, click Users.
  3. On the User Administration screen, search for the user by typing the user name in the Name field and clicking Search. You can use the asterisk (*) as a wildcard for search.
  4. Select the users you want to give access to.
  5. Click OK.




Backing up the Apache Derby database

If you want to back up the Apache Derby database embedded in the Report Server for ClearQuest, refer to http://db.apache.org/derby/.


Using the Report Server for ClearQuest

This section presents some common procedures for the Report Server for ClearQuest.


Accessing the Report Server for ClearQuest

The Report Server for ClearQuest uses a Web-based interface. To access the reporting interface:

  1. In the address bar of a browser, enter https://machinename.domain:portnumber/jazz/reportal/projects/Vega where machinename.domain is the hostname and domain of the machine where IBM Rational ClearQuest Reporting is installed, and portnumber is the port. See your administrator for detailed information on your machine.domain and portnumber.
  2. At the login prompt, enter your IBM Rational ClearQuest user name and password and click Login.




Working with reports
The following section presents information on common tasks for working with reports.




Designing reports

For information on designing reports, see the topic "About designing and running reports" in the IBM Rational ClearQuest information center.


Uploading report designs

To upload report designs:

  1. Point the mouse to the Reports folder where the report design is to be uploaded.
  2. Click the dropdown icon, and select New Report Design. The New Report Design window is displayed.
  3. Enter the name and description of the report design, and select the type of the report.
  4. If you want to share the report design with other users, select Shared.
  5. Click Browse, navigate to the directory containing the report design to be uploaded, and select the file. To upload more files, repeat this step.
  6. If you upload more than file, specify any one of them to be the master file. To do so, select the file in the list and click Master. Only a BIRT file or a Crystal Reports file can be a master file.
  7. Click Save.




Modifying report designs

To modify report designs:

  1. Download the report to be modified.
    1. In the reports navigator tree view, point the mouse to the report you want to modify and click Properties.
    2. From the Report Design Files section, select the report files to be modified.
    3. To download the report files to the local system, click the Download Reports icon. The file are downloaded as an archive (ZIP) file.
  2. Modify the report design.
    1. Extract the contents of the downloaded archive file.
    2. Modify the report design and save the changes.
  3. Remove the old design from the repository.
    1. In the reports navigator tree view, point the mouse to the report you want to modify and click Properties.
    2. From the Report Design Files section, select the report files to be deleted.
    3. Click the Delete Reports icon.
  4. Upload the modified report design files.




Sharing reports

By sharing a report, you make it visible to everyone who has access to the Report Server for ClearQuest on which the report is stored. You must have the administrator or lead user privilege to be able to share reports. For more information on user privileges, see User privileges.

To enable reports for sharing:

  1. Log in to the Report Server for ClearQuest as an administrator or a lead.
  2. Create a report folder and ensure to select the Share checkbox.
  3. Add uploaded reports to the shared folder, or upload new report designs to the folder. Ensure to select the Shared checkbox while uploading the report designs.




Saving reports as queries

Once the parameters have been passed into a report during execution, the report with the parameter values can be saved as queries.

To save a report query:

  1. Log in to the Report Server for ClearQuest.
  2. Navigate through the report folder hierarchy and locate the report design you want to run.
  3. Run the report.
  4. Enter appropriate parameter values and click Run.
  5. After the report is generated, click Save As.
  6. In the Save Report As dialog, specify the Save As type as Report Query, enter the name and description, select the parent folder, and specify whether the report should be public or private by selecting or clearing the Shared checkbox.




Saving report outputs as snapshots

Once a report has been generated from a report design or a report query, you can save the results by creating a report snapshot. Creating snapshots can be useful to preserve the result of a complex report or to share information with team members who may not have permission to run a given report.

To generate a report snapshot:

  1. Log in to the Report Server for ClearQuest.
  2. Navigate through the report folder hierarchy and locate the report design or report query you want to run.
  3. Run the report.
  4. After the report is generated, click Save As.
  5. In the Save Report As dialog, specify the Save As type as Report Snapshot, enter the name and description, select the parent folder, and specify whether the report should be public or private by selecting or clearing the Shared checkbox.




Viewing shared snapshots

You can view a snapshot created by others. There are two ways to navigate to a snapshot location:

  • By receiving an email notification from the creator of the snapshot.
  • By logging in to the Report Server for ClearQuest, and navigating to the report folder containing the snapshot.

To view a report snapshot received through an email notification:
  1. Obtain a link to the report snapshot. The link may be available in the notification email from the creator of the snapshot.
  2. Click the report link, or open it in a browser window.
  3. In the login screen for the Report Server for ClearQuest, enter your login information. You are taken directly to the report snapshot.

From the report snapshot, you can adjust report parameters, drill down, and perform all such actions that are available to you for any IBM Rational ClearQuest report.


Deleting reports

To delete a report:

  1. Point the mouse to any of the Reports folder nodes or Report Design nodes, and click the dropdown icon.
  2. Select Delete. The Reports folder or Report Design is removed from the folder.




Accessing bundled reports

You can access reports from the navigator bar in the Report Server for ClearQuest window. To see a report in the content view, click on the report name.


Working with folders

You can create folders, add reports to folders, and remove reports from folders.


Creating report folders

To create a report folder:

  1. Point the mouse to the Reports node, click the dropdown icon, and select New Report Folder. The New Report Folder window is displayed.
  2. Enter the report folder name, and select a parent folder. If you want to create a root folder, leave the value as none.
  3. If you are using the admin account or have Public Folder Administration rights in the IBM Rational ClearQuest user registry, you can share the folder. To do so, select Share.
  4. Click Save.


Adding reports to a folder

To add reports to a folder:

  1. Point the mouse to the node of the Reports folder, click the dropdown icon, and select Add Reports to Folder.
  2. Search for the report to be added, select the report and click the arrow button.
  3. Click Save to save the changes.




Removing reports from a folder

To remove a report from a folder:

  1. Point the mouse to any of the Reports folders or Report Design nodes, and click the dropdown icon.
  2. Select Remove from Tree. The Reports folder or Report Design is removed from the folder. You can reassign a report to a folder even after it has been removed from a folder.




Sharing folders

To allow shared access to folders:
  1. Point the mouse to the folder to be modified, and click the dropdown icon.
  2. Click Properties.
  3. Select Shared.




Displaying and editing folder properties

To display the properties for a report folder, and to edit the properties:

  1. Point the mouse to any of the Reports folder nodes or Report Design nodes, and click the dropdown icon.
  2. Click Properties. The following properties are displayed:
    • Report folder name
    • Parent folder
    • The sharing permission
  3. Edit the properties if your user account has the user privileges.




Using reports

You can email reports, print them, and export them as PDF and Microsoft Word files.


Emailing reports

To email a report:

  1. Run the report.
  2. Click the Save as button.
  3. In the Save Report As dialog, change the Save as setting to Report Snapshot.
  4. Enter values for the Name, Description, and Parent folder, and then select Shared.
  5. Save the report snapshot and then click on the snapshot in the Navigator.
  6. Click the e-mail icon in the snapshot toolbar to e-mail a link to the snapshot.




Printing reports

To print a report:

  1. Run the report.
  2. Click the print icon at the top right of the pane.
  3. In the window that pops up, click Print and click OK.




Exporting reports

To export a report:

  1. Run the report.
  2. Click the export icon at the top right of the pane.
  3. In the window that pops up, select the file format to be exported to, and click Export.




Working with sample reports

Four sample reports are included with the Report Server for ClearQuest:

  • Defects by State (CM)
  • Defects Summary (CM)
  • Defects by State (JNI)
  • Defects Summary (JNI)

Note: In this release, you can select only one StateParameterValue for the Defects by State reports.




Performance enhancements

To support robust performance:

  • Set the log trace levels to WARN.
  • Avoid including a large number of reports in a single folder. Having more than a hundred reports in a folder results in more time taken to expand folders for viewing.




Troubleshooting
This section describes troubleshooting procedures for user and administrative tasks.


Troubleshooting user tasks

Problem Probable cause Possible solution
Log-in problem
(CRRER0002E: Invalid User name or Password)
The Rational ClearQuest Super User account user name and password may not be correct in the Deploy_RCQR_eWAS.py and reportserver.properties file Ensure that the Deploy_RCQR_eWAS.py file has the correct user name and password of the Rational ClearQuest Super User account (see the following snippet):

# Set basic properties of custom security
attrs = '[[useRegistryServerId false][primaryAdminId %s][customRegistryClassName %s]]' % ('admin', 'com.ibm.rational.cq.was.userregistry.CQUserRegistry')
AdminConfig.modify(customUserRegistry, attrs)

# Set custom properties
customProps = {
'autoCreateJazzGroups':'true',
'jazzAdmins':'admin',
'jazzProjectLeads':'lead',
'cqDbSetName':'7.0.0',
'cqUserDbName':'SAMPL',
'cqConnectionURL':'connection-URL',
'cqConnectionUsername':'admin',
'cqConnectionPassword':'admin',
'cqConnectionPasswordEncrypted':'false',
}
The reportserver.properties file may not have the correct user name and password of the Rational ClearQuest Super User account or the connectionUrl may specify an invalid URL
  • Ensure that the reportserver.properties file has the correct user name and password of the Rational ClearQuest Super User account (see the following snippet):

user.registry.cq.dbSet=7.0.0
user.registry.cq.userDb=SAMPL
user.registry.cq.connectionUrl=http://localhost:12080/TeamWeb/services/Team user.registry.cq.connectionUsername=admin user.registry.cq.connectionPassword=admin user.registry.cq.connectionPassword.encrypted=false
  • Ensure the connectionUrl contains a valid and reachable URL to the TeamWeb, and that the URL does not have double-quotes surrounding it (just as the other values do not).
Login information for Report Server Profile's WebSphere Application Server Integrated Administration Console may be incorrect If login to the Report Server is yielding this error, also verify that you can login to the Report Server Profile's WebSphere Application Server Integrated Administration Console at URL: http://<host>:15060/ibm/console/

You should be able to login using your unencrypted username and password used when deploying the Report Server.

If you cannot login to the WAS console using this username and password, Report Server cannot connect to the CMserver listed to authenticate users, either. Verify that the correct encrypted password was used when deploying. You may need to contact IBM Rational support for assistance disabling and resetting the WAS security as multiple attempts may not clear out previously incorrect deployment settings, such as encrypted password.

Note: The encrypted password example in the Information Center uses "admin" as the example password. You must enter *your* corresponding password for the specified username when performing the encryption step.
Missing file: cqrpc.exe in Windows, cqrpc.sh on Linux The log file may have an entry: CRVAP0237E Resource 'cq.dbset:7.0.0': not found.
Look for the missing file (cqrpc.exe in Windows, cqrpc.sh on Linux) in the \RationalSDLC\common\CM\bin\ directory. If the file is missing, copy the file from the Rational ClearQuest install jar files.
The Rational ClearQuest server may not be reachable or may be stopped Verify that the Rational ClearQuest server is reachable and running. To do so, open a web browser and access http://localhost:12080/TeamWeb/services/Team. The following text must be returned: Hi there, this is a Web service!
Report Server for ClearQuest server cannot be stopped The user name and password needed to stop the server cannot be validated because the credentials provided are incorrect, or the correct credentials are not known 1. Disable administrative security. For details, see WebSphere Application Server Information Centre.
2. Make corrections in the configuration files.
3. Run Deploy_RCQR_eWAS.py again to enable security.
The Rational ClearQuest server may not be reachable or may be stopped Verify that the Rational ClearQuest server is reachable and running. To do so, open a web browser and access http://localhost:12080/TeamWeb/services/Team. The following text must be returned: Hi there, this is a Web service!
There may be errors in stopping the WAS service for the reportal profile. Run the following command to provide the credentials to stop the service: %RATIONAL_COMMON%/eWAS/bin/wasservice -add reportalprofile -serverName server1 -profilePath "%RATIONAL_COMMON%/CM/profiles/reportalprofile" -stopArgs "-username -password where username and password are same as the ones provided in the configuration files for the reportal.
The left-side navigation pane is not visible after logging in Insufficient system memory Increase the system memory or shut down some open applications.
No users are listed on the user admin page Ensure that:
  • the reportserver.properties file contains the correct credentials
  • the \RationalSDLC\ClearQuest\RCQR\server\rcqr-update-site\plugins\com.ibm.rational.stp_7.1000.0.v.jar folder contains the correct jar files
For details, see the solution under Log-in problem.



Troubleshooting administrative tasks
Task How to
Manually updating an RCQR jar file Manually updating the jar files is not recommended but if doing so is necessary, ensure that after you update the \RationalSDLC\ClearQuest\RCQR\server\rcqr-update-site or the reportalprofile\classes directory, you also clean up the reportalprofile\temp directory.
Modifying the log trace levels Log levels for the cqregistry.jar file can be set from the WAS admin console:
1. Start the WAS Admin console.
2. Click TroubleShooting >> Logs and Trace.
3. Click server1.
4. Click Change Log Details Levels.
5. In the list of classes available, look for the com.ibm.rational.cq.was.userregistry.CQUserRegistry file and change the log level. Logs for log levels below FINE go to the trace.log file.
To set the log levels for other classes:
1. Open the RationalSDLC/clearquest/RCQR/server/log4j_was.properties file.
2. Set the component log level:

# Set component log level
log4j.logger.com.ibm.rational.project.service.ProjectRestService=WARN
log4j.logger.com.ibm.rational.report.service.DataSourceRestService=WARN
log4j.logger.com.ibm.rational.report.service.ReportRestService=DEBUG
log4j.logger.com.ibm.rational.report.service.ReportCategorizationRestService=DEBUG
log4j.logger.com.ibm.rational.security.service.SecurityRestService=WARN
log4j.logger.com.ibm.rational.user.service.UserManagementService=WARN
log4j.logger.com.ibm.rational.user.service.UserRestService=DEBUG
log4j.logger.com.ibm.rational.user.registry.cq.CQUserRegistryService=DEBUG

Normally, the log level should be set to WARN. When a problem needs to be debugged, to capture more information set the log level to DEBUG.
Correcting the port number for the link for snapshots Add the following two properties to the /RationalSDLC/clearquest/RCQR/server/teamserver.properties file:

com.ibm.team.repository.server.repourl.port.http = 15080
com.ibm.team.repository.server.repourl.port.https = 15443

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Rational ClearQuest
Reporting

Software version:

7.1, 7.1.0.1, 7.1.0.2, 7.1.1, 7.1.1.1, 7.1.1.2, 7.1.1.3, 7.1.1.4, 7.1.1.5, 7.1.2, 7.1.2.1, 7.1.2.2

Operating system(s):

Windows

Reference #:

1315248

Modified date:

2014-05-12

Translate my page

Machine Translation

Content navigation