Bugzilla Installation & User Guide

There is an existing Bugzilla defect (Bug 345194) which is a request to add null support to Bugzilla's query capabilities. Until that bug is fixed, the only workaround we have found for allowing existing bugs to be found (for example, bugs created before the External ID custom field was added), is to use SQL to update the database directly, setting the custom field equal to the empty string. For example:

(Optional) Create a CrosslinkUrlField in Rally

It can be useful to have a clickable link in the Rally artifact that will bring up the corresponding bug in Bugzilla. The CrosslinkUrlField element in the RallyConnection section allows you specify the name of field that will contain this link.

Use the same process in Rally as for the Rally External ID above.

• We suggest a field name of BugzillaLink
• Must be a String type of field
• Make note of the name of this field for when you customize the RallyConnection section of your connector config file (see section 4.1.3)

(Optional) Create a CrosslinkUrlField in Bugzilla

Although Bugzilla doesn't have a weblink field, it can still be useful to have the URL to the corresponding item in Rally, stored in a field of type FreeText. A text selection of the URL and a right click of the URL to open the link in a new tab or window will then show the Rally item. Use the same process in Bugzilla as for the Rally External ID above. Note:

• We suggest a field name of RallyURL
• Make the field a FreeText type field
• Make note of the name of this field for when you customize the Bugzilla section of your connector config file (see section 4.1.3)

4.4 Edit the configuration file

The configuration file was part of the delivered zip file and should be in the same directory where you extracted the Ruby gem. For Bugzilla, the default configuration file has a name of bz_config.xml. We recommend making a backup copy of the bz_config.xml in case you need to reference a valid configuration file later.

Edit bz_config.xml by entering the appropriate values between each begin and end tag.

Each major section is surrounded by a tag to delineate that section. In the example above, here is a description of each section:

• RallyConnection
  Defines the connection information for Rally, including Rally URL, user, password, and so on.
• BugzillaConnection
  Defines the connection information for Bugzilla, including the Bugzilla URL, project, artifact type, and so on.
• Connector
  Defines the field mapping between the two systems. Generally, strings should be mapped to strings, integers to integers, and so on.
• ConnectorRunner
  Specifies the services to run and how often to run them.

Definition of tags in configuration file

Below is a more detailed explanation of each tag section in the configuration file:

Specification of elements contained in the RallyConnection section

<RallyConnection>

Tip:Escape special characters contained in a Rally Workspace or Project name that are markup sensitive. For example:

<BugzillaConnection>

Specification of elements contained in the Connector section

Note: Incrementally set up the connector. Start with a basic configuration file, test that you can connect to Bugzilla and Rally in a "test" environment. Once you validate this is setup correctly, then start customizing the field mapping and field handler sections.

Field mapping

The field mapping section is located between the <Connector> tags in the configuration file and defines what fields map between the two systems.

For example, this definition sets up a mapping between the Rally field Name with the field Headline in the other system. On a create or update, the connector will only update the Name field in Rally and the Headline field in the other system.

When you set up your mapping between the two systems, ensure the fields are compatible between the two systems (an integer field should map to an integer field in the other system, a rich text should map to a rich text in the other system).

Otherwise, you might experience situations where information is not created/updated between the two systems and you will see an error in the log file. For example, the connector will post an error for a particular work item if you try to post a string to a custom field of type integer in Rally.

You can add subsequent mappings by appending to this list. For example, this sets up a mapping to Rally Name → Headline, Rally Description → Description, Rally Priority → Priority:

If you are mapping a drop-down value in Rally to the other system, this assumes that the drop-down values match. Otherwise, the connector will throw an error letting you know the value was not found in the list.

If your drop-down values are different between the two systems, see the next section Mapping Drop-Down Values.

Bugzilla maintains a collection of comments for each bug, and the Description field in the Create Bug page simply creates the first comment. So, whereas the Rally defect Description is fairly static - for example, containing steps to reproduce the problem - Bugzilla's comments are more of a dynamic activity stream, a conversation that takes place as the bug is being worked on. Given the differences in purpose for these two fields, we do not recommend trying to map them.

A better approach is to create a new custom field (such as "Summary") in Bugzilla that is used for the same purpose as Description in Rally. It's a simple matter to map those fields together.

Given the extensible nature of the Enterprise Integration Framework upon which the Bugzilla Connector is based, it is certainly possible to write additional code to provide some transfer of information between Rally Description and Bugzilla Comments. For example, one could write a field handler to concatenate the collection of Comments from a Bugzilla bug and put that concatenation in the Rally Description. Care would need to be taken when updating from Rally to Bugzilla, however, to compare the Rally Description with the concatenation of Bugzilla Comments and not create a new comment (containing the Rally Description, which is the whole comment history) each time the connector runs. Here again, mapping Rally Description to a custom Bugzilla field would be a better approach than creating new comments. Rally's Professional Services organization is available for this kind of custom development.

Field handlers

Mapping Drop-Down Values
Mapping Users
Mapping Project Fields, etc.

4.5 Run the connector

Once the bz_config.xml is setup, you can start running the connector. On Windows, if you installed the Rally for Bugzilla Connector using the RallyforBugzillaConnector-<version>.exe, you can simply double-click on the startbz.bat file which is customarily installed in C:\Program Files\RallyforBugzillaConnector\startbz.bat. This will start the connector in a DOS command window and open a text window in which the log messages from the connector will be written as the processing proceeds.

Alternatively on Windows, if Ruby was installed using the One-Click Ruby Installer at RubyInstaller.org, you can simply open a DOS shell and type:

to start the service. Double-click on WinTail.exe to run WinTail. In WinTail, open the file rallylog.log to watch the log messages generated by the connector. This is an easy way to confirm that the connector is working properly, or to discover any errors.

To stop the service, use Control-C in the command shell.

Multiple configuration files

For users who want to map to more than one workspace in Rally, need to map multiple artifact types or need to map to multiple containers (such as domain/projects in Quality Center or ClearQuest databases) in the other system, setting up multiple configuration files may make sense. Rally recommends naming the configuration files using descriptive names for easier troubleshooting.

To run multiple instances of the connector for different configuration files, pass in the list of config files as arguments to the rally2_bugzilla_connector.rb script or rally2_bugzilla_connector.exe.

The connector will process the configuration files based on the command line argument order, and processes one file at at time.

Once it processes every configuration file, the connector will sleep based on the sleep value. The default is 15 minutes. To change the sleep value between runs, set this value (in minutes) as the last command line argument.

*We recommend a sleep value of 10 minutes or more and advise against anything less.

5.1 Troubleshooting the connector

Once the connector is running, all errors are written to a log file in the directory where the rally2_bugzilla_connector.exe was invoked. Informational messages, warnings and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the configuration file.

To see the most recent log messages on Windows, rename the file WinTail.dat to WinTail.exe and then double-click on the WinTail.exe and browse to the rallylog.log file.

Before the connector starts synchronizing objects between the two systems, it performs the following validations:

1. Connecting to Rally is successful
2. Connecting to the other system is successful
3. Fields in the field mapping section exist in Rally and in the other system
4. Each field handler has a corresponding field mapping section in the configuration file

To confirm the validation is successful without moving objects between the two systems, set the <Preview> tag in the configuration file to 'true'. This allows you to experiment with some different configuration options to debug an issue.

If you still cannot determine the root cause of an issue, then please email the entire log file and configuration file to Rally Support.

6.1 Tip

• Mapping Rally Projects: If you are copying defects from Bugzilla to Rally using the RallyReferenceFieldHandler with Projects, you may see a "Could not find Rally Project with name ..." error in the log file if the connector user does not have Editor permissions to that project in Rally.

7.1 Known Issues

1. Mapping Release/Iterations with Multiple Projects: If you are using a <RallyReferenceHandler> to map Releases/Iterations with the same name and multiple projects, you may receive an error if the Release/Iteration you are updating on the Defect references a different Project than the given Defect is assigned. The connector only returns the FIRST Release/Iteration with the matching name in Rally so it could have a reference to a Release/Iteration in a different project.