clearquest/dashboard integration...2.5. add the clearquest query gadget: you’ve added the chart...

© COPYRIGHT HCL TECHNOLOGIES LTD. 2018. ALL RIGHTS RESERVED

ClearQuest/Dashboard Integration

To get the maximum benefit of the dashboard, integrate it with ClearQuest so you can pull in

queries and charts. This is a two-step process. The first step is to update your CQWeb

TeamEAR with fixes to the gadgets. Do not use a production system to beta-test the

dashboard. Instead make a copy of any production data you want to test with and deploy a

ClearQuest Web installation just for testing. For best results use ClearQuest version

9.0.0.04.00_2017a. Newer versions may work (including 9.0.1 and newer, but some fixes that

went in after 9.0.0.04.00_2017a will not be available).

Unless otherwise noted, these steps should work for both Windows and Linux.

Prerequisites:

1) Installation of ClearQuest of version 9.0.0.04.00_2017a or later, on supported system.

2) ClearQuest Supported version of WebSphere.

1. Update ClearQuest Web TeamEAR

The first step is to update the TeamEAR on CQWeb with some fixes that are necessary for the

dashboard.

1.1. Login to CQWeb’s WebSphere Admin Console

In your browser go to your IBM Admin Console page and login. It is of the form:

<cqweb url>:12043/ibm/console

Port 12043 is the default https port for the IM installed CQWeb WebSphere IBM console. If

you installed CQWeb into your own WebSphere profile, then use the appropriate admin

console port for that profile. If you look in AboutThisProfile.txt file in the logs directory of

your WebSphere profile, you’ll see a line for “Administrative console secure port”. That would

be the correct port to use.


1.2. Go to web applications

Navigate to Applications->Application Types->WebSphere enterprise applications

1.3. Update TeamEAR

Check the box for TeamEAR and click Update. (note, you may also want to Export the

currently installed TeamEAR so you can revert to the original TeamEAR).

On the next screen, click on Browse… and select the TeamEAR.ear file packaged with the

dashboard beta.


Click Next four times, accepting the defaults. On the final page you can review before starting

the update, then click Finish. The update will start and will take a few minutes. When it is

done, Save the changes to the master, and then restart the CQWeb WebSphere profile. You

will now have a CQWeb server with an updated TeamEAR.

2. Configure ClearQuest/Dashboard Integration

This document describes the step by step process to integrate ClearQuest and Dashboards,

allowing you to use Chart and Query gadgets provided by ClearQuest:

2.1. Register an OAuth Consumer key

Login to CQWeb as an admin and register an OAuth consumer’s secret to create a new

consumer key. Refer to Registering an OAuth consumer key for details. Remember

your key and secret, you will need them in the next step.

2.2. Create an OAuth friend in DASHBOARDS administration section

A. Login to HCL Dashboards as an admin and go to Administration section:

https://www.ibm.com/support/knowledgecenter/en/SSSH5A_9.0.1/com.ibm.rational.clearquest.integrations.doc/topics/t_clm_int_consumer_key_reg.htm


B. Click on OAuth Friends link in the left navigation bar

C. Click on Add New OAuth Friend button

D. Now fill in the form.

a. Provide a Name and Description of your choice.

b. In the Gadget URI, put the URL for the CQ gadgets which is in the

following format:

<cqweb url>/oslc/repo/<reponame>/*

For e.g. http://localhost:9080/cqweb/oslc/repo/9.0.0/*

Using the wildcard (*) in the URL allows you to use the same OAuth tokens

for both the chart and query gadgets.

Alternatively, you may also specify the URL of the specific gadget like

http://localhost:9080/cqweb/oslc/repo/9.0.0/chartGadget

http://localhost:9080/cqweb/oslc/repo/9.0.0/queryGadget

in case you want to use just one of the gadgets.

Note: if you have multiple schema repos and want to allow access to each,

you should register an OAuth consumer for each one.

c. Put Consumer Key and Secret as per the values specified in section 2.1

Register an OAuth Consumer key.

http://localhost:9080/cqweb/oslc/repo/9.0.0/*






d. Service Name and other fields which are not mandatory should be left

empty for CQ integration.

E. Now click on Add button and you should now see an entry in the OAuth Friends list as shown below

2.3. Add the ClearQuest Chart gadget

You need to add the ClearQuest chart gadget to the widget store.

A. Click on the Widgets link in the Administration section and click Add new

widget:


B. In the form, put the URL for the ClearQuest Chart gadget in the Location field. The

chart URL is of the form - <CQ Web URL>/oslc/repo/<Repository

name>/chartGadget, e.g.


Note: gadgets are specific to the schema repository. If you want to be use gadgets

from different schema repositories, you must add each of them to the widget store.

C. Click on Get widget metadata button and you should see the following screen,

which is prepopulated with some of the metadata for the gadget. You should not

need to make any changes here.



D. Click on Add widget button. In the next screen, you can set some of the gadget

properties like Title, Description, categories etc. Suggestion: create a ClearQuest

category to make it easy to find ClearQuest gadgets in the widget store. Another

suggestion: if adding gadgets from multiple repositories, include the repository in

the Title, e.g. “CQ Chart – 9.0.0”


E. Click on Update widget button and you should see a success message as shown

below:


F. Now go back to the dashboard (the back arrow in the dashboard navbar will take

you back to the dashboard) and add the ClearQuest Chart gadget on a page in your

dashboard using either the Add Widgets menu option or the Add widgets to this

page link, as shown below


G. Go back to dashboard and you should find the ClearQuest Chart gadget on it

2.4. Login and configure the ClearQuest Chart gadget

ClearQuest chart gadgets support simple aggregate charts using data from a pre-defined

ClearQuest query. The query must already be defined and available in the workspace. The


chart will aggregate over one or more columns of data. The aggregation is a simple count. So if

you have a query returning a list of defects and aggregate over the Severity, then it will create

a chart showing the count of how many defects are at each Severity. You can also do a double-

aggregation, so if you chose State first, and then Severity, the chart would show a count of how

many records are in each state, and for each state it would show you how many are in each

Severity.

A. Click on Login link inside the CQ Chart gadget and you should get a login popup

as shown below: Put your credentials for ClearQuest and click on Continue

B. On successful authentication, you will get a popup that says

Note, once you are authorized by that gadgets OAuth service, you will not have to

log in again until the OAuth access token expires. By default, this only happens

when ClearQuest Web is restarted.

C. Close it and then you should be able to see the following screen in the ClearQuest

chart gadget:

D. Choose the appropriate User Database and click Continue to get the following

screen to select a query


E. Now select a query and click OK to get the following screen

F. Select a Chart type (Bar/Column/Pie), then choose a field you want to aggregate.

You may optionally select another field as well if you want to do double

aggregation. Note that, with Pie chart, you will be able to select only one field for

aggregation as it doesn’t have double aggregated capability.

Below are some examples for some combinations of Chart type and aggregation

fields:

1. Bar chart with single field (Severity) chosen will look like:

• Column Chart with two fields (Severity/State) for aggregation

• Bar Chart with two fields (Severity/State) for aggregation


• Pie Chart using aggregation based upon Severity

G. It is also possible to drill down into the chart to see records pertaining to that

section. Click on any section in any of the charts and you should see list of records

like as shown below

H. Click on Back button in the gadget to go back to the Chart view.

I. At any time, you can change the type of chart, the number of records per page

(shown when you drill down) and change the colour scheme used in the chart by

choosing Edit from the widget menu.


Known issue: you cannot change the query or aggregation fields once they are set (this will be

fixed).

2.5. Add the ClearQuest Query gadget:

You’ve added the Chart gadget to the widget store and added it to some of your dashboard

pages. Now, let’s do the same for the query gadget.

A. First add the ClearQuest Query gadget using the steps A to E in 2.3, except that

you need to use the query gadget URL:

<CQ Web URL>/oslc/repo/<Repository name>/queryGadget

e.g.:


B. Add the ClearQuest Query gadget to a page in your dashboard



C. Now go back to your dashboard and you should see the following screen

Note: Since we used the wildcard for the OAuth configuration, the dashboard knows that the

query gadget and chart gadget share the same OAuth access token. It does not ask you to

login again here. In case you have not added and logged in into a CQ gadget before, or if you

restarted ClearQuest Web, then you will see a login link and you will need to login as

described in the section 2.4.

2.6. Configure ClearQuest Query gadget:

A. Select the User Database and press Continue to get the following screen to

select the query to execute:


B. After selecting the query, press OK to execute the query see the results. If

you click on any record in the list, it will open CQ Web in a new browser

tab and show the corresponding record details.

C. You may change the number of records to show per page by going to the

Edit mode of the gadget as shown below and setting appropriate value


Known issue: When sharing dashboards that contain OAuth gadgets, people may see an error,

“Non-Secure Owner Page. Only page owners can grant OAuth approval”. This will be fixed in a

later release.

clearquest/dashboard integration...2.5. add the clearquest query gadget: you’ve added the chart...

Documents