Quality Center-JIRA Integration Kit Guide

Randall DeFauw
The Go To Group
randy.defauw@go2group.com

www.go2group.com

January 11, 2008

1
CONTENTS 1

Abstract
This integration kit allows collaboration between the Quality Center

test case tool and Atlassian's JIRA issue management system.

Contents
1 Architecture 3
1.1 The Mercury SOAP Service . . . . . . . . . . . . . . . . . . . . 4
1.2 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 4
1.2.1 Custom Field . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 Issue Tab Panel . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.3 Project Tab Panel . . . . . . . . . . . . . . . . . . . . . . 4
1.2.4 Issue Operation . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.5 Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 The Mercury Sync Service . . . . . . . . . . . . . . . . . . . . 5
1.4 The Mercury Sync Listener . . . . . . . . . . . . . . . . . . . . 5
1.5 Defect Replication Fields . . . . . . . . . . . . . . . . . . . . . . 5
1.5.1 Field Names . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5.2 Value Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.3 Field Types . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.5.4 Replicating Comments . . . . . . . . . . . . . . . . . . . . 8
1.6 Defect Replication Strategy . . . . . . . . . . . . . . . . . . . . . 9
1.6.1 Forcing replication from Quality Center to JIRA . . . . . 10
1.6.2 Forcing replication from JIRA to Quality Center . . . . . 10
1.6.3 Deleted Defects . . . . . . . . . . . . . . . . . . . . . . . . 11
1.7 Defect Replication Limitations . . . . . . . . . . . . . . . . . . . 11

2 Installation 12
2.1 Installation Summary . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3 The Mercury SOAP Service . . . . . . . . . . . . . . . . . . . . 13
2.3.1 Installing in Tomcat . . . . . . . . . . . . . . . . . . . . . 13
2.3.2 Installing in JBoss . . . . . . . . . . . . . . . . . . . . . . 14
2.4 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 15
2.5 The Mercury Sync Service . . . . . . . . . . . . . . . . . . . . 17
2.6 The Mercury Sync Listener . . . . . . . . . . . . . . . . . . . . 17

3 Usage 18
3.1 The Mercury SOAP Service . . . . . . . . . . . . . . . . . . . . 18
3.2 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 18
3.3 The Mercury Sync Service . . . . . . . . . . . . . . . . . . . . 19
3.4 The Mercury Sync Listener . . . . . . . . . . . . . . . . . . . . 20

4 FAQ 20
LIST OF TABLES 2

A Building the Integration Kit 21

A.1 The Mercury SOAP Service . . . . . . . . . . . . . . . . . . . . 21
A.2 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 21

List of Tables
1 Available JIRA Fields . . . . . . . . . . . . . . . . . . . . . . . . 6
2 Available Quality Center Fields . . . . . . . . . . . . . . . . . . . 7
3 Available Field Types . . . . . . . . . . . . . . . . . . . . . . . . 8
4 Synchronization Strategy . . . . . . . . . . . . . . . . . . . . . . 10

List of Figures
1 Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Replicate Now Issue Operation . . . . . . . . . . . . . . . . . . . 11
3 Test cases displayed while editing an issue . . . . . . . . . . . . . 18
4 Detail of associated test cases . . . . . . . . . . . . . . . . . . . . 18
5 Associated test cases for a project . . . . . . . . . . . . . . . . . 19
6 Searching for issues with test cases . . . . . . . . . . . . . . . . . 19
7 Associated JIRA issues displayed in test case . . . . . . . . . . . 20
1 ARCHITECTURE 3

1 Architecture
The integration kit consists of four pieces:
The Mercury SOAP Service is a SOAP wrapper around parts of Quality
Center's COM API. It allows remote access to the API.
The Mercury Kit JIRA Plug-in uses the Mercury SOAP Service to in-
teractively display test case information in JIRA.
The Mercury Sync Service uses the Mercury SOAP Service to pass issue
test case link data back to Quality Center.
The Mercury Sync Listener uses the Mercury SOAP Service to repli-
cate JIRA defect information into Quality Center.
Figure 1 shows the relationship between these pieces.

Figure 1: Architecture Overview

1 ARCHITECTURE 4

1.1 The Mercury SOAP Service

Quality Center provides a fairly comprehensive COM (Visual Basic/Visual Stu-
dio .NET) API. However, it makes no provisions for access by non-Microsoft
products. Therefore, the SOAP Service provides a SOAP wrapper around some
of this API. That way, there is a standard, platform and technology neutral
interface.
The SOAP service uses a Java to COM bridge, and is thus a Java based web
service.

1.2 The Mercury Kit JIRA Plug-in

This plug-in is the main user access point to the integration kit. The plug-
in consists of a custom eld, an issue tab panel, a project tab panel, an issue
operation, and a servlet.

1.2.1 Custom Field

The custom eld uses the Mercury SOAP Service to query Quality Center for
any available test cases, and shows those test cases in a drop-down list. The
user may select one or more test cases to link to an issue.

1.2.2 Issue Tab Panel

The panel displays more detailed information about each of the test cases linked
to an issue. It uses additional methods from the Mercury SOAP Service to
obtain the information.

1.2.3 Pro ject Tab Panel

The panel displays more detailed information about each of the test cases linked
to issues in one project. It uses additional methods from the Mercury SOAP
Service to obtain the information.

1.2.4 Issue Operation

The issue operation allows users to manually trigger a replication event for JIRA
issues.

1.2.5 Servlet

The servlet handles manually triggered replication events started by the issue
operation.
1 ARCHITECTURE 5

1.3 The Mercury Sync Service

This plug-in periodically sends issue-test case link data back to Quality Center.
A custom eld in Quality Center contains a list of linked JIRA issues, which is
populated by this service.
The service also periodically polls Quality Center for new or updated defects
that should be replicated to JIRA. A setting in the plug-in's properties le,
mercury.properties, determines whether defects in a particular Quality Cen-
ter project are replicated and, if so, which JIRA project they will be sent to
and which issue elds are synchronized (see page 15).
The service polls Quality Center for new or updated issues every time it
runs. It saves the time it last ran the query in a le; the location of this le is in
a conguration le (see page 15). The time value is stored as milliseconds since
1 January 1970, which is a standard Java time format. Resetting the value in
this le to 0 will eectively force the service to get all defects.
See Section 1.5 for a further discussion of defect replication.

1.4 The Mercury Sync Listener

This listener plug-in replicates new or updated JIRA defects to Quality Center.
See the discussion about eld synchronization for the Mercury Sync Service
(Section 1.5) for information about controlling which elds are synchronized.
A setting in the plug-in's properties le determines whether defects in a
particular JIRA project are replicated and, if so, which Quality Center project
they will be sent to (see page 15).
Since the listener performs replication as soon as issues are created or up-
dated, there are no problems with out-of-date data.

1.5 Defect Replication Fields

1.5.1 Field Names

The property le controls the list of elds to be synchronized, as explained on

page 15. Fields are identied by unique names. Note that defect synchronization
usually requires at least the issue's summary and status to be synchronized.
Additionally, certain key elds, such as the defect's ID, are always synchronized.

JIRA Fields For JIRA elds, most of the system elds have names listed in
Table 1. Custom elds should be identied by their user-visible custom eld
names, prexed by CF_; for example, if you have a custom eld called Customers,
you should identify it in the property le as CF_Customers.
1 ARCHITECTURE 6

JIRA Field Description Type

Name
AectedVersions Currently only supports syn- string
chronizing one version.
Assignee If user names in JIRA and string
Quality Center do not match,
be sure to provide a value
map.
Comments JIRA comments can be repli- string
cated to Quality Center (see
page 8).
Components Currently only support syn- string
chronizing one component.
CreateTime date
Description string
DueDate date
Environment string
FixVersions Currently only supports syn- string
chronizing one version.
IssueType Most likely requires a value string
map.
Priority Most likely requires a value string
map.
Reporter If user names in JIRA and string
Quality Center do not match,
be sure to provide a value
map.
Resolution Most likely requires a value string
map.
SecurityLevel Most likely requires a value string
map.
Status Most likely requires a value string
map.
Summary string
UpdateDate date
Table 1: Available JIRA Fields

Quality Center Fields Quality Center elds are identied by the names
given in Table 2; some elds are identied by regular names, while others are
identied by their database columns. Quality Center custom elds are always
identied by their database column. The Quality Center database documenta-
tion contains a list of available columns in the Quality Center database.
1 ARCHITECTURE 7

Note that some Quality Center elds contain HTML markers, which will be
removed when sent to JIRA.

Quality Center Field Name Description Type

AssignedTo If user names in JIRA and string
Quality Center do not match,
be sure to provide a value
map.
DetectedBy If user names in JIRA and string
Quality Center do not match,
be sure to provide a value
map.
Priority Most likely requires a value string
map.
Status Most likely requires a value string
map.
Summary string
BG_DESCRIPTION Description string
BG_DEV_COMMENTS Environment or developer string
notes
BG_SEVERITY Most likely requires a value string
map.
BG_DETECTION_DATE Creation date date
BG_DETECTION_VERSION Most likely requires a value string
map.
BG_PLANNED_CLOSING_VER Most likely requires a value string
map.
BG_ESTIMATED_FIX_TIME number
BG_ACTUAL_FIX_TIME number
BG_CLOSING_DATE date
BG_CLOSING_VERSION Most likely requires a value string
map.
Table 2: Available Quality Center Fields

1.5.2 Value Maps

Fields with lists of available values will most likely need a value map denition
in the property le, in order to allow the kit to translate values from one system
to another. For example, consider translating priority in JIRA into severity in
Quality Center; the property le may include entries that look like:
fieldlist=Summary|Summary|string,Status|Status|string,
Priority|BG_SEVERITY|string
1 ARCHITECTURE 8

Priority_map_jira=Blocker|5-Urgent,Critical|4-Very High,
Major|3-High,Minor|2-Medium,Trivial|1-Low
BG_SEVERITY_map_mercury=1-Low|Trivial,2-Medium|Minor,
3-High|Major,4-Very High|Critical,5-Urgent|Blocker
For elds like Resolution that may have no value initially, you can use the
placeholder value NULL. For example:

Resolution_map_jira=NULL|Unresolved,Fixed|Resolved
BG_USER_09_map_mercury=Unresolved|NULL,Resolved|Fixed
In this example, the resolution eld in JIRA is mapped to a user eld in Quality
Center. If the JIRA resolution has no value, it will be set to Unresolved in
Quality Center. A value of Unresolved in Quality Center will be ignored in
JIRA.

1.5.3 Field Types

Three types of elds are supported, as listed in Table 3.

Field Type Description

string
number
date Will be translated using a
standard date format.
Table 3: Available Field Types

1.5.4 Replicating Comments

Comments are handled very dierently in JIRA and Quality Center. In JIRA,
comments are stored as a log of individual entries. In Quality Center, comments
are stored in one eld as one block of text, with HTML markup used to format
the eld's appearance. For this reason, comments cannot be synchronized like
regular elds.
However, comments can be displayed in both systems. The Quality Center
comment eld, BG_DEV_COMMENTS, can be synchronized like a normal text eld
with any suitable JIRA eld, such as Environment or a text custom eld. With
this approach, comments from Quality Center can be displayed in JIRA. (Up-
dates made to this comment eld in JIRA will be replicated to Quality Center,
although the HTML format will not be preserved.)
JIRA comments can be sent to any suitable Quality Center eld. All com-
ments on a JIRA issue will be aggregated into one formatted block of text when
stored in Quality Center. In other words, all JIRA comments for an issue will be
1 ARCHITECTURE 9

stored in one eld in Quality Center. Updates made to that eld in Quality Cen-
ter will be ignored during replication, and overwritten if more JIRA comments
are sent over later.
For example:
Comments|BG_DEV_COMMENTS|string
An entry like this one in the fieldlist entry of mercury.properties will
cause JIRA comments to be aggregated and replicated to Quality Center's
BG_DEV_COMMENTS eld. Any updates made in Quality Center to the BG_DEV_COMMENTS
eld will be ignored and potentially overwritten as new JIRA comments are
replicated.
In summary, then, comments from Quality Center are available for a con-
strained two-way replication, with potential loss of formatting; comments from
JIRA are available only for one-way replication.

1.6 Defect Replication Strategy

When performing defect replication, a strategy is required to avoid double repli-

cations. That is, unless precautions are taken, an issue replicated from Quality
Center to JIRA may trigger a reverse replication from JIRA to Quality Center.
Table 4 lists the precautions taken to avoid this problem in the four replica-
tion scenarios.

Scenario Precautions Notes

New JIRA issue Will not be replicated to JIRA issue ID is
created Quality Center if the project stored with the
is not marked for replication; replicated Quality
if the issue already has a Center issue, and
Quality Center ID stored with the JIRA issue is
it; or if the issue's creator updated with the
is the special synchronization ID of the corre-
JIRA account. sponding Quality
Center defect.
JIRA issue updated Will not be replicated to
Quality Center if the project
is not marked for replication,
or if the updating user is the
special synchronization JIRA
account.
Continued on next page
1 ARCHITECTURE 10

Scenario Precautions Notes

New Quality Center Will not be replicated to Replicated JIRA
issue created JIRA if the project is not issue ID is stored
marked for replication, or if with the original
the issue already has a JIRA Quality Center
ID stored with it. issue, and the JIRA
issue is updated
with the ID of the
original Quality
Center defect. The
synchronization
user account is used
to create the issue
in JIRA.
Quality Center is- Will always be replicated in The synchroniza-
sue updated JIRA, but the JIRA listener tion user account is
will ignore that update since used to update the
it comes from the synchro- issue in JIRA.
nization user account.
Table 4: Synchronization Strategy

1.6.1 Forcing replication from Quality Center to JIRA

Occasionally it may be necessary to force a replication event to happen. For

example, if replication fails when a new JIRA issue is created, that issue would
never again be automatically replicated.
In order to force the replication process to pick up Quality Center defects
again, simply edit the value in the le indicated by the property lasttimefile
in mercury.properties (see page 15). This value is a standard Java time value
(in milliseconds since 1970). Setting it to a value in the past will force the
replication process to handle Quality Center defects created or updated since
that time.

1.6.2 Forcing replication from JIRA to Quality Center

In order to force JIRA issues to immediately replicate to Quality Center, use

the Replicate Now issue operation (see Figure 2). This operation is available
for issues that are eligible for replication, as specied in mercury.properties
(see page 15). Additionally, a user must have permission to edit the issue, or
the operation will not be available.
The operation will immediately attempt to replicate the JIRA issue to Qual-
ity Center. If the issue has never been successfully replicated, it will be treated
1 ARCHITECTURE 11

as a new issue, creating a new issue in Quality Center. If it has been replicated
in the past, it will be synchronized with its corresponding Quality Center issue.
When the operation is complete, the issue page will reload. You may have
no indication that the replication occurred, but you should see the updates in
Quality Center.

Figure 2: Replicate Now Issue Operation

1.6.3 Deleted Defects

Deleting a defect in JIRA will cause the corresponding defect in Quality Center
to be deleted. However, deleting a defect directly in Quality Center will not
aect the corresponding JIRA defect; currently we have no way to monitor
defects deleted manually in Quality Center.
Generally, deleting defects is a rare event, and we recommend that defects
be deleted in JIRA rather than Quality Center.

1.7 Defect Replication Limitations

There are a few limitations that aect how well the listener and service can
synchronize data between JIRA and Quality Center.

If Quality Center requires any elds that the listener does not or cannot
ll in, then the replication will fail.

The acceptable values for defect status in Quality Center must match
the acceptable values for defect status in JIRA, or a value map must be
provided.
2 INSTALLATION 12

The listener responds to standard JIRA events, such as Issue Created,

Issue Updated, and Issue Resolved. It may not respond to custom
events.

2 Installation
The installation and conguration of the integration kit is fairly involved, since
it involves installing services on two servers.
The packaged installer can be run using the script install.cmd on Windows
or install.sh on Linux. The installer will perform some of the installation
steps for JIRA, the web service, or both. You can run the installer in both the
JIRA server and the Quality Center server to do the appropriate parts of the
installation on both servers.
The instructions below indicate which parts of the installation will be done
by the installer, and which have to be performed manually.

2.1 Installation Summary

Below is an overview of the installation process. Each step is described in more

detail in subsequent sections.

Make sure you have compatible versions of Quality Center and JIRA.

Log in to Quality Center at least once from the Quality Center server, in
order to download the necessary libraries.

Install DLL les (EZJcomLib18.dll and JOTAClient.dll) in the

WINDOWS/SYSTEM32 directory. This step can be done by the installer.
Copy JAX libraries to your application server's lib folder. This step can
be done by the installer.

Copy MercuryInterface.war to your application server's automatic de-

ploy folder. This step can be done by the installer.

Verify that the web service is available.

Install the plug-in jar le, mercury_kit-4.1.jar, in JIRA's WEB-INF/lib
folder. This step can be done by the installer.

Edit the property le mercury.properties, and install it in JIRA's

WEB-INF/classes folder. Copying the le can be done by the installer.
Create custom elds TestCases and QcBugId in JIRA.
Add a Quality Center custom eld to hold a list of JIRA issues.
Create the le denoted by the lasttimefile property and enter one line
that contains the text 0.
2 INSTALLATION 13

Create the JIRA user denoted by the syncuser property and give it per-
mission to create and update issues in JIRA.

Use JIRA's administration page to add a new service of class

com.go2group.jira.services.MercuryService, and set the service to
run at an appropriate interval.

Add a Quality Center custom eld to hold a corresponding JIRA issue

key.

Use JIRA's administration page to add a new listener of class

com.go2group.jira.listeners.MercuryListener.

2.2 Prerequisites

The tested versions of various system components are listed below. Other ver-
sions may be compatible, but have not been tested.

Quality Center 9.2.

JIRA 3.11 or JIRA 3.12.1.
Tomcat 5.5, JBoss 4.2.2, or equivalent J2EE application server
JDK 1.6

2.3 The Mercury SOAP Service

The SOAP service is a Java web service which is installed on the Quality Center
server. It should run in any standard J2EE application server; specic instruc-
tions are provided below for Tomcat and JBoss.
You must have the Quality Center API libraries on the Quality Center server;
these are automatically installed by logging in to Quality Center from a web
browser.

2.3.1 Installing in Tomcat

1. Place the Java to COM bridge DLL les, EZJcomLib18.dll and JOTAClient.dll,
into the WINDOWS/SYSTEM32 directory. This step can be done by the in-
staller.

2. To deploy the web service in Tomcat, you will need the JAX-WS kit.
The JAX installer, JAXWS2.1.2-20070917.jar, is included in the JaM
distribution.

Run the JAX installer with this command:

java -jar JAXWS2.1.2-20070917.jar
The installer unpacks JAX into a directory named jaxws-ri.
2 INSTALLATION 14

Copy all of the jar les from the JAX-WS lib folder (jaxws-ri/lib)
to Tomcat's common/lib folder. This step can be done by the in-
staller.

3. Copy MercuryInterface.war to Tomcat's webapps folder. This step can

be done by the installer.

4. Restart Tomcat. Tomcat will automatically expand and deploy the WAR
le. The web service will then be available from the URL
<TOMCAT ROOT>/MercuryInterface/MercuryInterface.
5. Verify that the web service is available by accessing the URL <TOMCAT
ROOT>/MercuryInterface/MercuryInterface?wsdl in a browser.
6. Logging is controlled by the standard log4j properties le, log4j.properties,
which is located under the web application's WEB-INF/classes directory.

2.3.2 Installing in JBoss

The installer will not perform installation for JBoss.

1. Place the Java to COM bridge DLL les, EZJcomLib18.dll and JOTAClient.dll,
into the WINDOWS/SYSTEM32 directory.

2. To deploy the web service in JBoss, you will need the JAX-WS kit. The
JAX installer, JAXWS2.1.2-20070917.jar, is included in the JaM distri-
bution.

Run the JAX installer with this command:

java -jar JAXWS2.1.2-20070917.jar
The installer unpacks JAX into a directory named jaxws-ri.
Copy all of the jar les from the JAX-WS lib folder (jaxws-ri/lib)
to JBoss's server/default/lib folder.

3. Copy MercuryInterface.war to JBoss' server/default/deploy folder.

4. Restart JBoss. JBoss will automatically expand and deploy the WAR le.
The web service will then be available from the URL
<JBOSS ROOT>/MercuryInterface/MercuryInterface.
5. Verify that the web service is available by accessing the URL <JBOSS
ROOT>/MercuryInterface/MercuryInterface?wsdl in a browser.
6. Logging is controlled by the standard log4j properties le, log4j.properties,
which is located under the web application's WEB-INF/classes directory.
2 INSTALLATION 15

2.4 The Mercury Kit JIRA Plug-in

The following steps describe how to install the plug-in on a JIRA server.

1. Ensure the Mercury SOAP service is installed and congured on the Qual-
ity Center server.
2. Install the plug-in jar le, mercury_kit-4.1.jar, in JIRA's WEB-INF/lib
folder. This step can be done by the installer.
3. Set values in property le mercury.properties, which should be installed
in the WEB-INF/classes folder. Copying the JAR le can be done with
the installer.
user=username This value denes the Quality Center user name used
to authenticate with Quality Center.
password=password This value denes the password used to authen-
ticate with Quality Center.
host=server/TDBIN This value denes the Test Director URL.
field=TS_USER_00 This value denes the Quality Center custom
eld used to contain the list of linked issues. Please note that Quality
Center maintains a separate, internal ID for custom elds, besides the
displayed name. This property should be that internal ID, which the
Quality Center administrator can nd.
bugfield=BG_USER_00 This value denes the Quality Center cus-
tom eld used to contain the JIRA ID that corresponds to a Quality
Center defect. Please note that Quality Center maintains a sepa-
rate, internal ID for custom elds, besides the displayed name. This
property should be that internal ID, which the Quality Center ad-
ministrator can nd.
bugproj=jiraProj|mercuryDomain|mercuryProject This value de-
nes which JIRA projects should have their issues replicated to Qual-
ity Center, and which Quality Center projects the replicated defects
will be created in. The value is a comma delimited list of tuples.
Each tuple contains three values, delimited by the | character. The
rst value is the key of the JIRA project. The second value is the
domain of the corresponding Quality Center project, and the nal
value is the name of the corresponding Quality Center project.
mercproj=jiraProj|mercuryDomain|mercuryProject This value de-
nes which Quality Center projects should have their issues replicated
to JIRA, and which JIRA projects the replicated defects will be cre-
ated in. The value is a comma delimited list of tuples. Each tuple
contains three values, delimited by the | character. The rst value
is the key of the JIRA project. The second value is the domain of
the corresponding Quality Center project, and the nal value is the
name of the corresponding Quality Center project.
2 INSTALLATION 16

testproj=jiraProj|mercuryDomain|mercuryProject This value de-

nes which JIRA projects can link issues to test cases, and which
Quality Center projects the test cases can come from. The value is
a comma delimited list of tuples. Each tuple contains three values,
delimited by the | character. The rst value is the key of the JIRA
project. The second value is the domain of the corresponding Quality
Center project, and the nal value is the name of the corresponding
Quality Center project.
lasttimefile=c:/temp/time.txt This value denes the location of
the le that the synchronization service can use to store the last
synchronization time. This le should preferably be located in a
controlled directory, as the value stored in the le is critical to the
proper operation of the defect replication.
syncuser=syncuser This value denes the JIRA user name used to
create or update defects replicated from Quality Center. It is critical
that this JIRA account not be used for any other purpose. It should
have access to create and update issues in the JIRA projects aected
by replication.
soapport=http://MyHost:8080/MercuryInterface/MercuryInterfaceService
This value denes the address of the SOAP service, as it is deployed
in an application server on the Quality Center server.
license=license key This value holds the license key for the Quality
Center plug-in.
fieldlist=jiraFieldName|mercuryFieldName|type This value de-
nes which elds should be synchronized during defect replication.
The value is a comma delimited list of tuples. Each tuple contains
three values, delimited by the | character. The rst value is the name
of the eld in JIRA. The second value is the name of the correspond-
ing eld in Quality Center, and the nal value is the type of the eld.
See Section 1.5 for more information about how to dene this entry.
jiraField_map_jira=jiraValue|mercuryValue This value holds value
mappings for one eld. The name of the property is the name of the
eld in JIRA, followed by _map_jira. The property value is a comma
delimited list of mapping pairs. In each pair, the rst item is a value
in JIRA; the second item is the corresponding value for the eld in
Quality Center. See Section 1.5 for more details. If this entry ex-
ists for a eld, it will be used to translate JIRA values into Quality
Center values whenever data is sent from JIRA to Quality Center,
and every possible JIRA value should be mapped to a Quality Center
value.
mercuryField_map_mercury=mercuryValue|jiraValue This value
holds value mappings for one eld. The name of the property is the
name of the eld in Quality Center, followed by _map_mercury. The
property value is a comma delimited list of mapping pairs. In each
2 INSTALLATION 17

pair, the rst item is a value in Quality Center; the second item is the
corresponding value for the eld in JIRA. See Section 1.5 for more
details. If this entry exists for a eld, it will be used to translate
Quality Center values into JIRA values whenever data is sent from
Quality Center to JIRA, and every possible Quality Center value
should be mapped to a JIRA value.
4. Create the custom eld called TestCases of type MercuryField, and place
it on the default screen.
5. Create the custom eld called QcBugId of type Text Field. This eld
should not be visible on any screen; it merely holds the ID of the Quality
Center defect that corresponds to the issue in JIRA.
6. Test case information is displayed automatically on the issue tab panel
when the issue is displayed, and on the project tab panel when browsing
the project.

2.5 The Mercury Sync Service

The service is included in the Mercury Kit jar le, so you simply need to con-
gure it:
1. In Quality Center, add a Quality Center custom eld to hold JIRA
issues. The eld should hold strings. The name is not important, since
Quality Center uses an internal identier for custom elds (see 3); but a
descriptive name like LinkedIssues is appropriate.
2. Create the le denoted by the lasttimefile property (see 3), and enter
one line that contains the text 0.
3. Create the JIRA user denoted by the syncuser property (see 3), and give
it permission to create and update issues in the JIRA projects aected by
replication.
4. Use JIRA's administration page to add the new service of class
com.go2group.jira.services.MercuryService.
5. Set the service to run at an appropriate interval, perhaps every fteen
minutes.

2.6 The Mercury Sync Listener

The listener is included in the Mercury Kit jar le, so you simply need to
congure it:
1. In Quality Center, add a Quality Center custom eld to hold a cor-
responding JIRA issue key. The eld should hold strings. The name is
not important, since Quality Center uses an internal identier for custom
elds; but a descriptive name like JIRA ID is appropriate.
3 USAGE 18

2. Use JIRA's administration page to add the new listener of class

com.go2group.jira.listeners.MercuryListener.

3 Usage
3.1 The Mercury SOAP Service
There is no direct user interaction with the SOAP service; it is used by the other
components to interact with Quality Center.

3.2 The Mercury Kit JIRA Plug-in

Using the JIRA plug-in is easy. When editing an issue, JIRA will display a
list of available Quality Center test cases in the custom eld called TestCases
(Figure 3). Select one or more test cases to associate with the issue.

Figure 3: Test cases displayed while editing an issue

When viewing an issue, JIRA will display information about each associated
test case in an issue tab panel, as shown in Figure 4.

Figure 4: Detail of associated test cases

When browsing a project, JIRA will display information about all of the test
cases linked to any issue in the project, using a project tab panel (Figure 5).
3 USAGE 19

Figure 5: Associated test cases for a project

You can also search for issues that contain certain test cases, as shown in
Figure 6.

Figure 6: Searching for issues with test cases

3.3 The Mercury Sync Service

This service runs automatically, and there is no direct user interaction. The
service tells Quality Center which JIRA issues are associated with a test case,
and displays this information in a custom eld, usually called LinkedIssues
(see Figure 7). This eld should never be modied manually, since the service
will overwrite it.
4 FAQ 20

Figure 7: Associated JIRA issues displayed in test case

3.4 The Mercury Sync Listener

This listener runs automatically, and there is no direct user interaction. The
listener replicates new or updated JIRA issues to Quality Center immediately;
the defects will be seen in Quality Center. They will contain the JIRA issue
key in a Quality Center custom eld, usually called JIRA ID. This eld should
never be modied manually, since the listener relies on this information in order
to synchronize data.

4 FAQ
This section details some common problems when installing and running the
integration kit.

1. There is no communication between JIRA and Quality Center, and the

JIRA log complains about bad endpoint addresses for the SOAP service.
Check that the value of the soapport property is set correctly in the
conguration le. (See page 15)

2. When trying to log in to Quality Center, you receive some sort of RPC
error message, and can not log in.Run the Test Director Check program
(typically called CheckTD.exe). It may indicate the problem; one com-
mon problem is if the user account that runs the Quality Center services
changes its password.
A BUILDING THE INTEGRATION KIT 21

A Building the Integration Kit

The web service portions of the kit can be built by building the SOAP service
project in Netbeans, or by using Ant. The JIRA plug-in, listener, and service
must be built using the JIRA development kit.

A.1 The Mercury SOAP Service

Build the project using Ant. Simply run the publish target in the build script.
This generates the WAR le, MercuryInterface.war.

A.2 The Mercury Kit JIRA Plug-in

The JIRA plug-in has to be built every time the web service denition changes.
The following steps assume that you are working at the top level of the plug-in
directory, in the JIRA development kit.

1. Set the mercury-wsdl property in build.xml. This property should re-

ect the location of the Mercury SOAP Service on a target Quality Center
server.

2. Run ant wsdl-generate to build the WSDL stubs

3. Run maven jar to build the jar le, mercury_kit-4.1.jar

Index
Architecture, 3 Limitations, 11
Mercury Kit JIRA Plug-in, 4 Manual Override, 10
Mercury SOAP Service, 4 Strategy, 9
Mercury Sync Listener, 5 Value Maps, 7
Mercury Sync Service, 5
Replicated Defect Fields, 5 Tomcat, 13

Comment Replication, 8 Usage

Mercury Kit JIRA Plug-in, 18
Installation, 12 Mercury SOAP Service, 18
Mercury Kit JIRA Plug-in, 15 Mercury Sync Listener, 20
Mercury SOAP Service, 13 Mercury Sync Service, 19
Mercury Sync Listener, 17
Mercury Sync Service, 17
Summary, 12

JBoss, 14

Mercury Kit JIRA Plug-in

Architecture, 4
Installation, 15
Usage, 18
Mercury SOAP Service
Architecture, 4
Installation, 13
Usage, 18
Mercury Sync Listener
Architecture, 5
Installation, 17
Limitations, 11
Usage, 20
Mercury Sync Service
Architecture, 5
Installation, 17
Limitations, 11
Usage, 19

Replication
Comments, 8
Field Names, 5
JIRA, 5
Quality Center, 6
Field Types, 8
Forcing, 10

22