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 . . . . . . . . . . . . . . . . . . . . 41.2 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 4

1.2.1 Custom Field . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.2 Issue Tab Panel . . . . . . . . . . . . . . . . . . . . . . . . 41.2.3 Project Tab Panel . . . . . . . . . . . . . . . . . . . . . . 41.2.4 Issue Operation . . . . . . . . . . . . . . . . . . . . . . . . 41.2.5 Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3 The Mercury Sync Service . . . . . . . . . . . . . . . . . . . . 51.4 The Mercury Sync Listener . . . . . . . . . . . . . . . . . . . . 51.5 Defect Replication Fields . . . . . . . . . . . . . . . . . . . . . . 5

1.5.1 Field Names . . . . . . . . . . . . . . . . . . . . . . . . . 51.5.2 Value Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 71.5.3 Field Types . . . . . . . . . . . . . . . . . . . . . . . . . . 81.5.4 Replicating Comments . . . . . . . . . . . . . . . . . . . . 8

1.6 Defect Replication Strategy . . . . . . . . . . . . . . . . . . . . . 91.6.1 Forcing replication from Quality Center to JIRA . . . . . 101.6.2 Forcing replication from JIRA to Quality Center . . . . . 101.6.3 Deleted Defects . . . . . . . . . . . . . . . . . . . . . . . . 11

1.7 Defect Replication Limitations . . . . . . . . . . . . . . . . . . . 11

2 Installation 12

2.1 Installation Summary . . . . . . . . . . . . . . . . . . . . . . . . 122.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 The Mercury SOAP Service . . . . . . . . . . . . . . . . . . . . 13

2.3.1 Installing in Tomcat . . . . . . . . . . . . . . . . . . . . . 132.3.2 Installing in JBoss . . . . . . . . . . . . . . . . . . . . . . 14

2.4 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 152.5 The Mercury Sync Service . . . . . . . . . . . . . . . . . . . . 172.6 The Mercury Sync Listener . . . . . . . . . . . . . . . . . . . . 17

3 Usage 18

3.1 The Mercury SOAP Service . . . . . . . . . . . . . . . . . . . . 183.2 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 183.3 The Mercury Sync Service . . . . . . . . . . . . . . . . . . . . 193.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 . . . . . . . . . . . . . . . . . . . . 21A.2 The Mercury Kit JIRA Plug-in . . . . . . . . . . . . . . . . . . 21

List of Tables

1 Available JIRA Fields . . . . . . . . . . . . . . . . . . . . . . . . 62 Available Quality Center Fields . . . . . . . . . . . . . . . . . . . 73 Available Field Types . . . . . . . . . . . . . . . . . . . . . . . . 84 Synchronization Strategy . . . . . . . . . . . . . . . . . . . . . . 10

List of Figures

1 Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . 32 Replicate Now Issue Operation . . . . . . . . . . . . . . . . . . . 113 Test cases displayed while editing an issue . . . . . . . . . . . . . 184 Detail of associated test cases . . . . . . . . . . . . . . . . . . . . 185 Associated test cases for a project . . . . . . . . . . . . . . . . . 196 Searching for issues with test cases . . . . . . . . . . . . . . . . . 197 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 QualityCenter'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-Microsoftproducts. Therefore, the SOAP Service provides a SOAP wrapper around someof this API. That way, there is a standard, platform and technology neutralinterface.

The SOAP service uses a Java to COM bridge, and is thus a Java based webservice.

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 issueoperation, and a servlet.

1.2.1 Custom Field

The custom �eld uses the Mercury SOAP Service to query Quality Center forany available test cases, and shows those test cases in a drop-down list. Theuser 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 linkedto an issue. It uses additional methods from the Mercury SOAP Service toobtain the information.

1.2.3 Project Tab Panel

The panel displays more detailed information about each of the test cases linkedto 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 JIRAissues.

1.2.5 Servlet

The servlet handles manually triggered replication events started by the issueoperation.

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 ispopulated by this service.

The service also periodically polls Quality Center for new or updated defectsthat 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 toand which issue �elds are synchronized (see page 15).

The service polls Quality Center for new or updated issues every time itruns. It saves the time it last ran the query in a �le; the location of this �le is ina con�guration �le (see page 15). The time value is stored as milliseconds since1 January 1970, which is a standard Java time format. Resetting the value inthis �le to 0 will e�ectively 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 aparticular JIRA project are replicated and, if so, which Quality Center projectthey 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 onpage 15. Fields are identi�ed by unique names. Note that defect synchronizationusually 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 inTable 1. Custom �elds should be identi�ed by their user-visible custom �eldnames, pre�xed 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

Name

Description Type

A�ectedVersions Currently only supports syn-chronizing one version.

string

Assignee If user names in JIRA andQuality Center do not match,be sure to provide a valuemap.

string

Comments JIRA comments can be repli-cated to Quality Center (seepage 8).

string

Components Currently only support syn-chronizing one component.

string

CreateTime dateDescription stringDueDate dateEnvironment stringFixVersions Currently only supports syn-

chronizing one version.string

IssueType Most likely requires a valuemap.

string

Priority Most likely requires a valuemap.

string

Reporter If user names in JIRA andQuality Center do not match,be sure to provide a valuemap.

string

Resolution Most likely requires a valuemap.

string

SecurityLevel Most likely requires a valuemap.

string

Status Most likely requires a valuemap.

string

Summary stringUpdateDate date

Table 1: Available JIRA Fields

Quality Center Fields Quality Center �elds are identi�ed by the namesgiven in Table 2; some �elds are identi�ed by regular names, while others areidenti�ed by their database columns. Quality Center custom �elds are alwaysidenti�ed 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 beremoved when sent to JIRA.

Quality Center Field Name Description Type

AssignedTo If user names in JIRA andQuality Center do not match,be sure to provide a valuemap.

string

DetectedBy If user names in JIRA andQuality Center do not match,be sure to provide a valuemap.

string

Priority Most likely requires a valuemap.

string

Status Most likely requires a valuemap.

string

Summary stringBG_DESCRIPTION Description stringBG_DEV_COMMENTS Environment or developer

notesstring

BG_SEVERITY Most likely requires a valuemap.

string

BG_DETECTION_DATE Creation date dateBG_DETECTION_VERSION Most likely requires a value

map.string

BG_PLANNED_CLOSING_VER Most likely requires a valuemap.

string

BG_ESTIMATED_FIX_TIME numberBG_ACTUAL_FIX_TIME numberBG_CLOSING_DATE dateBG_CLOSING_VERSION Most likely requires a value

map.string

Table 2: Available Quality Center Fields

1.5.2 Value Maps

Fields with lists of available values will most likely need a value map de�nitionin the property �le, in order to allow the kit to translate values from one systemto another. For example, consider translating priority in JIRA into severity inQuality 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 theplaceholder 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 QualityCenter. If the JIRA resolution has no value, it will be set to Unresolved inQuality Center. A value of Unresolved in Quality Center will be ignored inJIRA.

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 astandard date format.

Table 3: Available Field Types

1.5.4 Replicating Comments

Comments are handled very di�erently in JIRA and Quality Center. In JIRA,comments are stored as a log of individual entries. In Quality Center, commentsare stored in one �eld as one block of text, with HTML markup used to formatthe �eld's appearance. For this reason, comments cannot be synchronized likeregular �elds.

However, comments can be displayed in both systems. The Quality Centercomment �eld, BG_DEV_COMMENTS, can be synchronized like a normal text �eldwith any suitable JIRA �eld, such as Environment or a text custom �eld. Withthis 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 whenstored 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 commentsare sent over later.

For example:Comments|BG_DEV_COMMENTS|string

An entry like this one in the fieldlist entry of mercury.properties willcause JIRA comments to be aggregated and replicated to Quality Center'sBG_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 arereplicated.

In summary, then, comments from Quality Center are available for a con-strained two-way replication, with potential loss of formatting; comments fromJIRA 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 QualityCenter 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 issuecreated

Will not be replicated toQuality Center if the projectis not marked for replication;if the issue already has aQuality Center ID stored withit; or if the issue's creatoris the special synchronizationJIRA account.

JIRA issue ID isstored with thereplicated QualityCenter issue, andthe JIRA issue isupdated with theID of the corre-sponding QualityCenter defect.

JIRA issue updated Will not be replicated toQuality Center if the projectis not marked for replication,or if the updating user is thespecial synchronization JIRAaccount.

Continued on next page

1 ARCHITECTURE 10

Scenario Precautions Notes

New Quality Centerissue created

Will not be replicated toJIRA if the project is notmarked for replication, or ifthe issue already has a JIRAID stored with it.

Replicated JIRAissue ID is storedwith the originalQuality Centerissue, and the JIRAissue is updatedwith the ID of theoriginal QualityCenter defect. Thesynchronizationuser account is usedto create the issuein JIRA.

Quality Center is-sue updated

Will always be replicated inJIRA, but the JIRA listenerwill ignore that update sinceit comes from the synchro-nization user account.

The synchroniza-tion user account isused to update theissue in JIRA.

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. Forexample, if replication fails when a new JIRA issue is created, that issue wouldnever again be automatically replicated.

In order to force the replication process to pick up Quality Center defectsagain, 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 thereplication process to handle Quality Center defects created or updated sincethat time.

1.6.2 Forcing replication from JIRA to Quality Center

In order to force JIRA issues to immediately replicate to Quality Center, usethe Replicate Now issue operation (see Figure 2). This operation is availablefor issues that are eligible for replication, as speci�ed in mercury.properties

(see page 15). Additionally, a user must have permission to edit the issue, orthe 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 replicatedin the past, it will be synchronized with its corresponding Quality Center issue.

When the operation is complete, the issue page will reload. You may haveno indication that the replication occurred, but you should see the updates inQuality Center.

Figure 2: Replicate Now Issue Operation

1.6.3 Deleted Defects

Deleting a defect in JIRA will cause the corresponding defect in Quality Centerto be deleted. However, deleting a defect directly in Quality Center will nota�ect the corresponding JIRA defect; currently we have no way to monitordefects deleted manually in Quality Center.

Generally, deleting defects is a rare event, and we recommend that defectsbe deleted in JIRA rather than Quality Center.

1.7 Defect Replication Limitations

There are a few limitations that a�ect how well the listener and service cansynchronize 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 matchthe acceptable values for defect status in JIRA, or a value map must beprovided.

2 INSTALLATION 12

• The listener responds to standard JIRA events, such as Issue Created,Issue Updated, and Issue Resolved. It may not respond to customevents.

2 Installation

The installation and con�guration of the integration kit is fairly involved, sinceit involves installing services on two servers.

The packaged installer can be run using the script install.cmd on Windowsor install.sh on Linux. The installer will perform some of the installationsteps for JIRA, the web service, or both. You can run the installer in both theJIRA server and the Quality Center server to do the appropriate parts of theinstallation on both servers.

The instructions below indicate which parts of the installation will be doneby 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 moredetail 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, inorder to download the necessary libraries.

• Install DLL �les (EZJcomLib18.dll and JOTAClient.dll) in theWINDOWS/SYSTEM32 directory. This step can be done by the installer.

• Copy JAX libraries to your application server's lib folder. This step canbe 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/libfolder. This step can be done by the installer.

• Edit the property �le mercury.properties, and install it in JIRA'sWEB-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 linethat 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 classcom.go2group.jira.services.MercuryService, and set the service torun at an appropriate interval.

• Add a Quality Center custom �eld to hold a corresponding JIRA issuekey.

• Use JIRA's administration page to add a new listener of classcom.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 Centerserver. It should run in any standard J2EE application server; speci�c 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 webbrowser.

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 JaMdistribution.

• 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 canbe 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. TheJAX 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 con�gured on the Qual-ity Center server.

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

3. Set values in property �le mercury.properties, which should be installedin the WEB-INF/classes folder. Copying the JAR �le can be done withthe installer.

• user=username This value de�nes the Quality Center user name usedto authenticate with Quality Center.

• password=password This value de�nes the password used to authen-ticate with Quality Center.

• host=server/TDBIN This value de�nes the Test Director URL.

• field=TS_USER_00 This value de�nes the Quality Center custom�eld used to contain the list of linked issues. Please note that QualityCenter maintains a separate, internal ID for custom �elds, besides thedisplayed name. This property should be that internal ID, which theQuality Center administrator can �nd.

• bugfield=BG_USER_00 This value de�nes the Quality Center cus-tom �eld used to contain the JIRA ID that corresponds to a QualityCenter defect. Please note that Quality Center maintains a sepa-rate, internal ID for custom �elds, besides the displayed name. Thisproperty 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 defectswill 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 thedomain of the corresponding Quality Center project, and the �nalvalue 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 replicatedto JIRA, and which JIRA projects the replicated defects will be cre-ated in. The value is a comma delimited list of tuples. Each tuplecontains three values, delimited by the | character. The �rst valueis the key of the JIRA project. The second value is the domain ofthe corresponding Quality Center project, and the �nal value is thename 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 whichQuality Center projects the test cases can come from. The value isa comma delimited list of tuples. Each tuple contains three values,delimited by the | character. The �rst value is the key of the JIRAproject. The second value is the domain of the corresponding QualityCenter project, and the �nal value is the name of the correspondingQuality Center project.

• lasttimefile=c:/temp/time.txt This value de�nes the location ofthe �le that the synchronization service can use to store the lastsynchronization time. This �le should preferably be located in acontrolled directory, as the value stored in the �le is critical to theproper operation of the defect replication.

• syncuser=syncuser This value de�nes the JIRA user name used tocreate or update defects replicated from Quality Center. It is criticalthat this JIRA account not be used for any other purpose. It shouldhave access to create and update issues in the JIRA projects a�ectedby replication.

• soapport=http://MyHost:8080/MercuryInterface/MercuryInterfaceServiceThis value de�nes the address of the SOAP service, as it is deployedin an application server on the Quality Center server.

• license=license key This value holds the license key for the QualityCenter 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 containsthree values, delimited by the | character. The �rst value is the nameof 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 de�ne this entry.

• jiraField_map_jira=jiraValue|mercuryValue This value holds valuemappings 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 commadelimited list of mapping pairs. In each pair, the �rst item is a valuein JIRA; the second item is the corresponding value for the �eld inQuality 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 QualityCenter values whenever data is sent from JIRA to Quality Center,and every possible JIRA value should be mapped to a Quality Centervalue.

• mercuryField_map_mercury=mercuryValue|jiraValue This valueholds value mappings for one �eld. The name of the property is thename of the �eld in Quality Center, followed by _map_mercury. Theproperty 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 thecorresponding value for the �eld in JIRA. See Section 1.5 for moredetails. If this entry exists for a �eld, it will be used to translateQuality Center values into JIRA values whenever data is sent fromQuality Center to JIRA, and every possible Quality Center valueshould be mapped to a JIRA value.

4. Create the custom �eld called TestCases of type MercuryField, and placeit on the default screen.

5. Create the custom �eld called QcBugId of type Text Field. This �eldshould not be visible on any screen; it merely holds the ID of the QualityCenter defect that corresponds to the issue in JIRA.

6. Test case information is displayed automatically on the issue tab panelwhen the issue is displayed, and on the project tab panel when browsingthe 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 JIRAissues. The �eld should hold strings. The name is not important, sinceQuality Center uses an internal identi�er for custom �elds (see 3); but adescriptive name like LinkedIssues is appropriate.

2. Create the �le denoted by the lasttimefile property (see 3), and enterone line that contains the text 0.

3. Create the JIRA user denoted by the syncuser property (see 3), and giveit permission to create and update issues in the JIRA projects a�ected byreplication.

4. Use JIRA's administration page to add the new service of classcom.go2group.jira.services.MercuryService.

5. Set the service to run at an appropriate interval, perhaps every �fteenminutes.

2.6 The Mercury Sync Listener

The listener is included in the Mercury Kit jar �le, so you simply need tocon�gure 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 isnot important, since Quality Center uses an internal identi�er 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 classcom.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 othercomponents 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 alist 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 associatedtest 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 testcases 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 inFigure 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. Theservice 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 modi�ed manually, since the servicewill 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. Thelistener replicates new or updated JIRA issues to Quality Center immediately;the defects will be seen in Quality Center. They will contain the JIRA issuekey in a Quality Center custom �eld, usually called JIRA ID. This �eld shouldnever be modi�ed manually, since the listener relies on this information in orderto synchronize data.

4 FAQ

This section details some common problems when installing and running theintegration kit.

1. There is no communication between JIRA and Quality Center, and theJIRA log complains about bad endpoint addresses for the SOAP service.Check that the value of the soapport property is set correctly in thecon�guration �le. (See page 15)

2. When trying to log in to Quality Center, you receive some sort of RPCerror 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 serviceschanges 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 serviceproject in Netbeans, or by using Ant. The JIRA plug-in, listener, and servicemust 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 de�nition changes.The following steps assume that you are working at the top level of the plug-indirectory, 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 Centerserver.

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, 3Mercury Kit JIRA Plug-in, 4Mercury SOAP Service, 4Mercury Sync Listener, 5Mercury Sync Service, 5Replicated Defect Fields, 5

Comment Replication, 8

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

JBoss, 14

Mercury Kit JIRA Plug-inArchitecture, 4Installation, 15Usage, 18

Mercury SOAP ServiceArchitecture, 4Installation, 13Usage, 18

Mercury Sync ListenerArchitecture, 5Installation, 17Limitations, 11Usage, 20

Mercury Sync ServiceArchitecture, 5Installation, 17Limitations, 11Usage, 19

ReplicationComments, 8Field Names, 5JIRA, 5Quality Center, 6

Field Types, 8Forcing, 10

Limitations, 11Manual Override, 10Strategy, 9Value Maps, 7

Tomcat, 13

UsageMercury Kit JIRA Plug-in, 18Mercury SOAP Service, 18Mercury Sync Listener, 20Mercury Sync Service, 19

22