Go2Group JaM Plugin Atlassian JIRA add-on for HP Quality Center Quick Install Guide Version 5.5 April 2009
Table of Contents Go2Group JaM Plugin Requirements... 3 What s Needed... 3 Go2Group JaM Plugin Quick Installation Guide... 4 Overview... 4 Basis Scenario... 5 Install Quality Center SOAP Service... 6 Introduction... 6 Installation... 7 Installing the Quality Center Kit Plugin for JIRA... 9 The Quality Center Sync Service... 10 The Quality Center Sync Listener... 11 Additional Configuration... 13 Go2Group JaM Plugin Tips and Troubleshooting... 21 General Suggestions... 21 Updates and Upgrades... 21 Frequently Asked Questions... 22 Go2Group JaM Plugin Additional Information... 24 Technical Support... 24 Sales Support... 24 Learn More... 24 2
Go2Group JaM Plugin Requirements What s Needed To upgrade the Go2Group JaM Plugin, you will need the following: Atlassian JIRA Enterprise, v3.11 or later HP Quality Center v9.0 or later JDK 1.5 or later The Go2Group JaM Plugin supports Windows and Linux environments. In addition to the technical requirements above, you will need administrator-level permissions for Atlassian JIRA, HP Quality Center, and the Application Server. There is minor interaction needed with Quality Center. 3
Go2Group JaM Plugin Quick Installation Guide Overview The following upgrade guide is to be used when installing the Go2Group JaM Plugin, v5.5, in a typical environment. For details in specific sections, please review the full installation guide. The installation consists of three (3) main sections: Installing the Quality Center SOAP Service Installing the Go2Group JaM Plugin Additional Configuration These steps assume the latest package has been downloaded from the Go2Group Support Site. 4
Basis Scenario This Quick Installation Guide is provided to help you get the Go2Group JaM Plugin up and running in a minimal amount of time. The installation and configuration follows a basic scenario, where we have tested the process to ensure a successful outcome. Go2Group highly encourages customers to use the default project settings for both systems, as the following instructions suggest. The Quick Install Guide assumes customers have not customized the Status and Priority settings in JIRA. In this Quick Install Guide, the following fields will be replicated: JIRA Field Quality Center Field Summary Status Priority CreateTime Reporter Summary Status BG_SEVERITY BG_DETECTION_DATE DetectedBy 5
Install Quality Center SOAP Service Introduction To install the Quality Center SOAP service, a Windows machine is required Windows XP or Window 2003 Server are acceptable versions of Windows. Go2Group recommends installing the Quality Center SOAP service on the same machine that Quality Center is installed on for better performance. If Quality Center is installed within a Linux environment, a separate Windows machine can be used to install the Quality Center SOAP service. Before installing the Quality Center SOAP service, JDK v1.5 or later must be installed on the same machine and system variable JAVA_HOME must be configured properly. The following ports should be made available on the machine used to install the Quality Center SOAP service: 2098 2099 4560 5444 Before installing the Quality Center SOAP service, Quality Center must be accessed from the machine that the Quality Center SOAP service is being installed on. 6
Installation An installation wizard is provided to ease the installation of the Go2Group JaM Plugin. 1. Run the file Mercury_SOAP_Service.exe found in the Go2Group JaM Plugin package. Click the Next button to continue.! 2. Specify the installation directory for the SOAP service. Click the Next button to continue. 3. Specify the port number for the SOAP service. Click the Next button to continue. 7
4. Start the Go2Group Mercury SOAP Service in a Windows Services window: 5. Verify that the web service is available by accessing the following URL in a web browser: http://server:port/mercuryinterface/mercuryinterface?wsdl For example: http://localhost:8080/mercuryinterface/mercuryinterface?wsdl! Before continuing, please check the following steps. 1. Log onto Quality Center via the machine that the Quality Center SOAP service was installed to. 2. Confirm a screen similar to the screenshot above is visible. 8
Installing the Quality Center Kit Plugin for JIRA 1. Install the JAR file by running the following file: Mercury_Kit_JIRA_Plug-in_windows.exe Click the Next button to continue.! 2. Next, specify the location of JIRA. Click the Next button to continue.! 3. Next, configure the mercury.properties file.! If the mercury.properties file already exists, the following configuration screen will not be displayed. The table below describes each field in detail. Click the Next button to continue. Field QC login user name QC login password QC host Description Defines the Quality Center user name used to authenticate with QC. Please make sure that this account has the project administration permission. Defines password used to authenticate with QC. Defines the QC URL. For example: http://qcserver:8080/qcbin. QC soapport Defines the address of the SOAP service, which was installed in Section 2. Once the properties above have been defined, restart JIRA. 9
Initialize JaM One the installer has been completed, we ll need to setup the synchronization components to match specific environment needs. Begin the configuration process by accessing the Administration panel within JIRA. Scroll down to the System group, then select the JaM Configuration link, as shown in the image below.! Next click on the Initialize JaM link. The JaM Initializer will assist you in creating custom fields, setting up the listener and service. 10
The JaM Configuration screen appears. This screen sets whether Defects, Test Cases, and / or Requirements will be used during the replication process between QC and JIRA. Select the appropriate module, then click the Initialize JaM button, as shown in the image below. After the Initialize JaM button has been clicked, the following items are created in JIRA: QcBugId custom field - The Quality Center ID - Holds QC Bug ID values within JIRA. MercuryListener - Leveraging the listener service in JIRA, the Mercury Listener provides the synching trigger between JIRA and QC. 11
MercuryService Test Case Module: Test Case custom field will be created. Requirement Module: Requirement custom field will be created. 12
Additional Configuration The following instructions provide an overview of additional configurations available by using the Go2Group JaM Plugin. Please note, these instructions are provided as an example. Your environment is likely different and may need additional support. To begin the additional configuration, open the JaM Configuration under Administration / System: Note We will ignore the following fields as they were configured in Section 3 above: User Password Host SOAPPORT JaM License JIRA ID To configure this field, a custom field will need to be created in the Defect section of Quality Center. In Quality Center, log in to the specific project. Add custom field named JIRA ID. In this example, BG_USER_06 is used for the JIRA ID field name. 13
Linked Issues If QC TestCases do not need to link with JIRA Issues, then skip this field (leave field empty). To configure this field, you need to create a custom field in the Test section of Quality Center. In Quality Center, log in to the specific project. Add custom field named LinkedIssues. Specify at least 200 for the Field Length. In this example, TS_USER_06 is used for the Linked Issues field name. Make sure the values here match your environment settings. The values will be validated when you click Next. If an alert appears, please review the values to ensure they are correct. 14
Issue Replication (JIRA ==> Mercury) This field indicates what project will need replicated from JIRA to Quality Center. Issue Replication (Mercury ==> JIRA) This field indicates what project will need replicated from Quality Center to JIRA. Test Case This field indicates what Test Cases in Quality Center will be linked to JIRA. This entry can be skipped if Test Cases in Quality Center do not need to be linked with Issues in JIRA (leave this field empty). Requirements This field indicates what Requirements in Quality Center will be linked to JIRA. This entry can be skipped if Requirements in Quality Center do not need to be linked with Issues in JIRA (leave this field empty). 15
bugfield If you create a JIRA ID custom field in Mercury, you should be able to select JIRA ID in the list. lasttimefile This value defines the location of the file that the synchronization service can use to store the last synchronization time. During the default installation, the file can be located at: <JIRA_HOME>\atlassian-jira\WEB-INF\classes\lasttime.txt To store the file in a different location, choose another directory and place an empty file named lasttime.txt within the chosen directory. Enter the directory path into the lasttimefile property. syncuser This value defines 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. 16
db and dbschema These fields are required if you are using MS SQL Server: db = SQLSERVER dbschema = (schema in SQL Server) Field Mapping The default settings should not be changed during the quick installation. The default settings resemble the following entries here we only map the basic and required fields such as Summary, Status, etc. 17
Value Mapping of Status Here are the default mappings for the status schemes in JIRA and Quality Center. If the status schemes in JIRA and Quality Center are the default schemes, these settings do not need editing. 18
Value Mapping of Priority Here are the default mappings for the priority scheme in JIRA and severity scheme in Quality Center. If the priority and severity schemes are configured as default, these settings do not need editing. 19
Reporter Value Mapping If you want to map the administrator JIRA as the QCADMIN in Quality Center, the following property must be set accordingly. Please be aware of the direction when mapping the user names. Clicking Save will activate all settings. 20
Go2Group JaM Plugin Tips and Troubleshooting General Suggestions Go2Group provides technical support for its entire line of products. If you run into any issues when installing or configuring the Go2Group JaM Plugin, please contact us. Updates and Upgrades Go2Group provides regular updates to its products. These updates include performance enhancements and minor bug fixes. To review previous, current, and upcoming updates and upgrades, please visit the Go2Group support site at: support.go2group.com A customer login is required to access the support site above. Please contact Go2Group for your login credentials. 21
Frequently Asked Questions This section details some common problems when installing and running the integration kit. You can find more frequently asked questions at: support.go2group.com Q: There is no communication between JIRA and Quality Center, and the JIRA log complains about bad endpoint addresses for the SOAP service. A: Check that the value of the soapport property is set correctly in the configuration file Q: When trying to log in to Quality Center, an RPC error message appears and you are not able to log in. A: Run the Mercury Check program (typically called CheckTD.exe). It may indicate the problem; a common problem is if the user account that runs the Quality Center services changes its password. Q: Does the Go2Group JaM Plugin support updates? A: The JaM Plugin supports updates in most cases. There are two cases where the JaM Plugin doesn't update properly: When there is only one JIRA issue tied to a test case, and that test case link is removed, the linkedissues custom field in Mercury won t be updated. The current solution is for the user to manually delete the reference to the JIRA ticket in QC. We are currently exploring a method of solving this issue programmatically without impacting the performance between QC and JIRA. The link between test case and defect or requirement and defect in JIRA will be updated when the corresponding issue in Mercury is modified. JaM use the modified time in Mercury to decide which issue should be replicated to JIRA and the modified time won t be updated when you modify a link in Quality Center. Q: I receive the message "com.go2group.mercury.mercuryinterface] ezjcom.jcomexception: Failed to Connect Project" in the mercury.log. What is happening? A: Make sure the user account in mercury.properties (user=xxxx) can login into the specified Project, create and modify defects in QC. Don't forget to log in to Quality Center at least once from the Quality Center server, in order to download the necessary libraries. Q: The JIRA and QC do not appear to be synchronizing. A: All JIRA required must be either populated in QC or a default value must be provided in a value map. Otherwise the QC->JIRA synchronization might fail. 22
Q: How can I make all of JaM s Log messages going into another file. A: You can add the following lines in log4j.properties, please find someone who is familiar with log4j to help you. log4j.appender.r=org.apache.log4j.rollingfileappender log4j.appender.r.file=c:/jira/log/jira-jam-plug-in.log log4j.appender.r.maxfilesize=10mb log4j.appender.r.maxbackupindex=10 log4j.appender.r.layout=org.apache.log4j.patternlayout log4j.appender.r.layout.conversionpattern=%d %t %p [%c{4}] %m%n log4j.category.com.go2group = DEBUG, console, filelog, R log4j.additivity.com.go2group = false c:/jira/log/jira-jam-plug-in.log is where you want the log. Please note the in the "log4j.category.com.go2group = DEBUG, console, filelog, R", DEBUG is the bug level. This line maybe you already have it. Just add ",R" in the line. Restart JIRA. Try to see if you can see the JaM log in another log file. Q: I try to configure a transition in the mercury.properties file, but it didn t work when the status changed. Why? A: Please make sure that if you configure any condition and validator in the workflow, syncuser has the right to execute the transition. Q: When an item is closed in QC, after synchronizing it is closed in JIRA as well, but the workflow actions "resolve" and "Close Issue" are still possible. According to the JIRA administration interface the built-in workflow only allows "Reopen Issue" from status "Closed". A: The JaM Plugin will replicate issue values between QC and JIRA without executing the workflow in JIRA. The reason is you can change an issue to any status in QC but in JIRA you need to trigger the workflow action and then you can change the status. In an effort to prevent users from changing the wrong status and causing the replication to fail, the JaM Plugin only updates the value - it does not execute the workflow for the normal scenario. The JaM Plugin is only updating the issue data. As a workaround, you can define "transition=resolved Closed 701" or autoexecutetransition=y in the mercury.properties file. As an example, you have an issue with status set to "Resolved" in JIRA. QA wants to close this issue in QC. QA changes this issue to the Closed status. The JaM Plugin will then try to replicate this issue from QC to JIRA: First, it will only update the status value to Close in JIRA. Since the JIRA issue status has changed from "Resolved" to "Closed", the transition (701) will be executed, which is the "Close Issue" workflow action. The Reopen action will now be the only workflow action. 23
Go2Group JaM Plugin Additional Information Technical Support Go2Group provides technical support for its entire line of products, including the Go2Group JaM Plugin. Go2Group technical support is available by telephone, email, and a Go2Group JaM Plugin specific customer support ticket system: By telephone: +1 877 442 4669 By email: support@go2group.com By ticket: support.go2group.com A customer login is required to access the support site above. Please contact Go2Group for your login credentials. To help resolve your issue quickly, please provide the log from the Go2Group JaM Plugin, as follows; mercury.properties atlassian-jira.log (<JIRA_HOME>/atlassian-jira/WEB-INF/classes/mercury.properties) Please change log level by adding "log4j.category.com.go2group=debug, console, filelog" and log4j.additivity.com.go2group = false in log4j.properties. Restart JIRA and run some test cases. You can find log4j.properties in <JIRA_HOME>/atlassian-jira/WEB-INF/classes qc.log (<TOMCAT_HOME or JBOSS_HOME>/logs/qc.log) Sales Support Go2Group provides sales support for its entire line of products, including the Go2Group JaM Plugin. Go2Group sales support is available by telephone and email: By telephone: +1 877 442 4669 By email: sales@go2group.com A customer login is required to access the support site above. Please contact Go2Group for your login credentials. Learn More For more information on Go2Group, its products, and its services, please visit our website at: www.go2group.com For more information on JIRA, please visit the Atlassian website at: www.atlassian.com For more information on Quality Center, please visit the HP website at: www.hp.com 24
25