Bugzilla Installation & User Guide

Print this topicEmail this topic

The Rally connector for Bugzilla can synchronize multiple Bugzilla record types with many types of Rally artifacts. The Rally connector for Bugzilla allows customers to use Rally for Agile lifecycle management while still using Bugzilla for management of bugs. Some of the features of the connector:

  • Choose any work item
  • Filter only certain work items to synchronize
  • Map most fields
  • Choose field transfer direction
  • Default field values
  • Easily map users
  • Easily map different drop-down fields between systems
  • Easily map to Rally's project structure
  • Customize multiple extension points

The Rally connector for Bugzilla runs as a Ruby script on a machine inside your network. The connector is configured through an XML file. A log file is created to track all changes made in Rally and Bugzilla by the connector. The connector requires that a custom field exists in each system to store the unique ID of the linked objects in the other system. The connector copies fields from Rally and Bugzilla based on a field mapping that the user has specified in their configuration file. You can map standard and custom fields between the two systems.

The connector uses the REST API for Bugzilla and requires at the minimum Bugzilla 3.6.x, with the latest tested version being Bugzilla 4.0.x. Additionally, UTF-8 is used for encoding (default on new installations) with versions 0.9 and 1.0 of the Bugzilla REST API. If you intend to run the connector on something other than Windows, it will require Ruby 1.9.2-p290 (the connector will not work with Ruby 1.8.x)

The connector provides five services to synchronize objects between Rally and Bugzilla:

  • Copy bugs created in Bugzilla to Rally work items
  • Copy work items created in Rally to Bugzilla bugs
  • Update Rally work items based on changes made to Bugzilla bugs
  • Update Bugzilla bugs based on changes made to Rally work items
  • Update Rally work items and Bugzilla bugs

The configuration file specifies which services to run, and in what order.

An alternative update service, UPDATE_RALLYFIELDS_AND_OTHER, searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields in to Rally.

This makes the chances of overwrites of data highly unlikely. The only scenario where an overwrite might occur is if Peter made changes in Rally and Al made changes in the other system for the same fields, the Rally information is copied over to the other system (possibly overwriting the data of the other system), then all data is copied over to the Rally system.

It is important to recognize that the data models of Rally and Bugzilla are not identical and, as such, the two systems are only partially compatible. We recommend you take some time to identify the key data items you want to track in both systems and consider what you want the policy to be as far as having a primary system of record. You'll see specific information later in this document discussing some of the trade-offs to be considered and some potential approaches.

This installation and user guide includes:

Basic installation steps

  1. Install the connector (run the installer or extract the zip).
  2. Make configuration changes in Rally and in Bugzilla.
  3. Edit the bz_config.xml to reflect your environment.
  4. Run rally2_bugzilla_connector program (.rb or .exe) to start the synchronization process.

Download the connector

System setup

  • The following people will be involved in getting fields set up in both Rally and Bugzilla:
    • Bugzilla user with the ability to add fields to bugs
    • Rally user with administrator privileges for setup (only user access is needed to run the connector).
  • Consider the process you want to set up between Rally and Bugzilla:
    • Where do objects start and end their lifecycle?
    • Which fields need to be updated?
  • Identify a test environment in Bugzilla to use for testing the connector
  • Identify a test Rally workspace and project to use for testing the connector

Software and hardware requirements

The following are the hardware and software requirements to install and run the Rally connector for Bugzilla:

  • A Rally subscription
  • A Win32 OS (if using a Windows machine)
  • Supported stable version of Bugzilla using UTF-8 (default on new installations) with Bugzilla REST API Version

    To install the Bugzilla REST API, review the Bugzilla REST API: Your Installation section for more information.


  • Ruby 1.9.2-p290 (this connector will not work with Ruby 1.8.x)
    • To install Ruby on Windows, we recommend the one-click installer which can be found at http://rubyinstaller.org/downloads/. Click on the Ruby 1.9.2-p290 link to download the installer.
    • You must install as an administrator on Windows for the path and environment variable settings to take effect (check this option during the install).
    • By default, Ruby 1.9.2-p290 is installed in the C:\Ruby19 directory.
Note: The Rally connector for Bugzilla has been developed and tested with the following:
  • Bugzilla 4.4.1
  • Bugzilla REST API 1.3
  • Ruby 2.0.0-p247

Install the connector

(Optional) If your site uses a proxy server to access Rally, you will need to set the http_proxy environment variable. To accomplish this on Windows 7:

  1. From Start, right-click on Computer, then select Properties.
  2. Click Advanced system settings.
  3. On System Properties, click Environment Variables.
  4. On Environment Variables, click New under System Variables.
  5. On New System Variables, enter http_proxy in the Variable name field, then enter your proxy's full http URL in the Variable value field (for example, http://www-cache:8000).
  6. Click OK (three times) to save and exit this process.

    You may need to restart your system in order for the change to take effect.

Pre-installation checklist

  • Access to a test environment and installation of Bugzilla with the Bugzilla REST API installed
  • Rally administrator privileges are needed for setup, but only user access needed to run the connector
  • Proxy server details if the machine used to run the connector uses a proxy server

Installation for Windows

Double-click the RallyConnectorforBugzillaInstall-<version>.exe to open the install wizard. Follow the prompts to complete the installation.

install

The Windows installer will install the following files (by default in C:\Program Files\RallyConnectorforBugzilla):

  • rally2_bugzilla_connector.exe—Executable to run the connector
  • bz_config.xml—Sample configuration file
  • WinTail.exe*—Utility to tail the log file output for debugging purposes
  • startbz.bat—Batch file that automatically runs the connector and shows the log file; useful for testing

*WinTail is a free text file tail utility for Windows, generously made available by Bare Metal Software Pty Ltd. for redistribution without restriction. We have found it to be far superior to Notepad and other text editors for watching log files in real time as they are updated by the connector.

Installation for Linux and Mac

  1. Unzip and extract the contents of the zip file locally on your machine (for example, C:\rally). The contents of the zip include these files:
    • <connector_name>_config.xml—Sample configuration file
    • rally2_<connector_name>_connector.rb—Ruby file used to run the connector
    • yeti-x.x.x.gem—Gem (library) that includes all of the code needed for the connector
    • WinTail.dat—Utility to tail the log file output for debugging purposes (rename from .dat to .exe)
  2. Install the required Ruby gems by entering:
    gem install -y builder
    gem install json_pure --version 1.2.4
    gem install httpclient
    gem install rally_api
    gem install sanitize
    gem install nokogiri
  3. Using a proxy:
    gem install -y -p http://proxyhost:portnumber builder
  4. Answer yes to any questions about installing required dependencies.
  5. Install the yeti gem by navigating to where you extracted the zip file:
    cd rally
    gem install yeti*.gem

Bugzilla setup

Create an External ID custom field in Bugzilla

Contact your Bugzilla administrator to perform these updates:

  1. Go to AdministrationCustom Fields.
  2. Click Add a new custom field.
  3. Enter a Name and Description.
  4. Select Free Text as the Type.
    caution_icon Caution: Do not specify this field as the default type of BugID as that type will result in the connector being unable to identify and select bugs for transfer to Rally.
  5. Select Can be set on bug creation.
  6. Click Create.

Make note of the name of this field (for example, cf_field_name). All Bugzilla custom fields begin with the cf_ prefix. Enter this value (cf_*) in the <ExternalIDField> element of the configuration file under the <BugzillaConnection> section.

caution_icon Caution: External ID field is not searchable for existing bugs
When you create the custom field for External ID, it is added to any existing bugs in the database, but its value for those bugs is null. The Bugzilla web service API does not permit querying for fields whose contents is null, so the connector service which updates bugs from Bugzilla to Rally will never find them.

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:

mysql> UPDATE bugs SET cf_rally_id = "" WHERE cf_rally_id IS NULL;

(Optional) Create a <CrosslinkUrlField> in Bugzilla

Bugzilla does not have a clickable weblink field, but it can still be useful to have the URL to the corresponding item in Rally stored in a FreeText type field. Select the text of the URL, then right-click to open the link in a new tab or window to display the Rally item. Use the same process in Bugzilla as for the Rally External ID. Note:

  • We suggest a field name of RallyURL
  • Make the field a FreeText type
  • Make note of the name of this field for when you customize the Bugzilla section of your connector configuration file

Rally setup

Create an External ID field in Rally

  1. Log into Rally as a workspace or subscription administrator.
  2. Go to Setup → Workspaces & Projects.
  3. Select the workspace that you wish to map to Bugzilla.
  4. On the detail page, click Work Products & Fields in the sidebar and ensure the Work Product Type selected is Defect (or whichever work item you are mapping).
  5. Click Actions → New Field.
  6. Enter a name of BugzillaID, display name of BugzillaID (name and display name must match), and type of String. Note: You can choose a different name for the custom field in Rally, but the name you choose must conform to these rules:
    • Begin with an uppercase letter
    • Less than 41 characters
    • No underscores, dashes, or spaces

Make note of the name of this field. Once you start using the connector, this will contain the external id of the Bugzilla entity you are mapping between the two systems.

(Optional) Create a <CrosslinkUrlField> in Rally

It can be useful to have a clickable link in the Rally artifact that will open 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.

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

Configure the connector

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.

<Config>
        <RallyConnection>
                <Url>rally1.rallydev.com</Url>
                <WorkspaceName>Workspace Name</WorkspaceName>
                <Projects>
                        <Project>Project Name 1</Project>
                </Projects>
                <User>user@company.com</User>
                <Password>password</Password>
                <ArtifactType>Defect</ArtifactType>
                <ExternalIDField>BugzillaID</ExternalIDField>
                <CrosslinkUrlField>BugzillaLink</CrosslinkUrlField>
        <!--    <UpdateSelectors>
                        <UpdateSelector>state = Open</UpdateSelector>
                        <UpdateSelector>priority = High</UpdateSelector>
                </UpdateSelectors>
        -->
        </RallyConnection>

        <BugzillaConnection>
                <Url>mybugzilla:3000</Url>
                <User>user@company.com</User>
                <Password>password</Password>
                <ArtifactType>bug</ArtifactType>
                <IDField>id</IDField>
                <ExternalIDField>cf_rally_id</ExternalIDField>
        <!--    <CopySelectors>
                        <CopySelector>state = Open</CopySelector>
                        <CopySelector>severity = Low</CopySelector>
                </CopySelectors>
        -->
        </BugzillaConnection>
       
        <Connector>
                <FieldMapping>
                        <Field><Rally>Name</Rally>      <Other>summary</Other></Field>
                        <Field><Rally>State</Rally>     <Other>status</Other></Field>
                        <Field><Rally>Severity</Rally>  <Other>severity</Other></Field>
                        <Field><Rally>Priority</Rally>  <Other>priority</Other></Field>
                </FieldMapping>
        </Connector>

        <ConnectorRunner>
                <Preview>False</Preview>
                <LogLevel>Debug</LogLevel>
                <Services>UPDATE_BUGZILLA_TO_RALLY,  COPY_BUGZILLA_TO_RALLY</Services>
        </ConnectorRunner>
</Config>

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.

Field mapping

The field mapping section is located within the <Connector> element in the configuration file. More detailed information can be found in the FAQ section How to Map Fields.

caution_icon Mapping the Bugzilla description field is not recommended
When you create a new Bugzilla bug, there is a Description field available on the page and some customers have inquired about mapping this field to the Description field in Rally defects. This is not as straightforward to implement as it first appears.

Bugzilla maintains a collection of comments for each bug, and the Description field in the Create Bug page simply creates the first comment (of many possible future comments). 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 is much easier 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. Be careful 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.

Map Bugzilla keywords to Rally tags

Example configuration file syntax for using the <RallyKeyword2TagFieldHandler>:

<Config>
        ....
        <Connector>
                ....
                <RallyFieldHandlers>
                        <RallyKeyword2TagFieldHandler>
                                <Type>Array</Type>
                        </RallyKeyword2TagFieldHandler>
                <RallyFieldHandlers>
        </Connector>
        ....
</Config>

Map users

# <BugzillaOwnerFieldHandler>
#   <FieldName></FieldName>
# </BugzillaOwnerFieldHandler>

Examples of supported and not-supported use:

  • Bugzilla to Rally:

    There are two keywords in Bugzilla, kw1 and kw2. The COPY_BUGZILLA_TO_RALLY service will create two new tags in Rally, kw1 and kw2.

  • Rally to Bugzilla:

    Create a new defect in Rally and assign kw1 and kw2 to it as tags. The COPY_RALLY_TO_BUGZILLA service will create a bug in Bugzilla with kw1 and kw2 keywords (because the keywords already exist in Bugzilla).

  • Unsupported: Rally tags to non-existent keywords in Bugzilla:

    There are two tags in Rally, tag1 and tag2, but there are no identically spelled keywords in Bugzilla. The COPY_RALLY_TO_BUGZILLA service results in the error:

    WARN : BugzillaConnection.initialize - Exception Bugzilla error: Unknown Bugzilla error.
                     Title: 'Invalid Keyword' detected trying to create Bugzilla bug

Individual fields may also have a directionality specified, whereby that specific field will be mapped in one direction only. For more information on this feature, see Field Directionality.

Field handlers

Map drop-down values
Map user names
Map reference fields from Rally (such as Project, Release)

XML setup

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

<RallyConnection>

Tag Name Description Sample Values
<Url>
Required
Server used to connect to Rally (excluding the HTTPS prefix, as the connector adds https:// to what is specified). sandbox.rallydev.com
rally1.rallydev.com
myRally.mydomain.com
192.168.23.24
<User>
Required
Login name for user to make the Web Services requests to create and update work items in Rally. user@company.com
<Password>
Required
Password associated with the above <User>. Note: The connector will encode this password string and update it in the configuration file to avoid clear-text passwords being stored. mypassword
<WorkspaceName>
Required
Workspace in Rally you want to copy and update work items. My Workspace MyWorkspace
<Projects>
Required
Contains a list of project tags. Each tag refers to one Rally project that will be used when finding new Rally work items to copy to the other system. For updating work items from Rally to the other system, all projects in <WorkspaceName> are considered. At least one Rally project must be specified in this tag. <Project>Rally1</Project>
<Project>Rally2</Project>
<ArtifactType>
Required
Type of artifact you want to create and update in Rally. (Defect, defect),
(Story, UserStory, HierarchicalRequirement), TestCase
<ExternalIDField>
Required
Rally custom string field (Name and Display Name must be identical) that stores the unique ID for the other system. See Create an External ID Field in Rally. BugzillaID
<SuppressDeprecationWarning> Changes the WARN message about Rally WSAPI version deprecation in the logfile to an INFO message.
<CrosslinkUrlField> Rally custom field containing a hyperlink to the corresponding bug in Bugzilla. BugzillaLink
<CopySelectors>
   <CopySelector>
Criteria to use when finding new Rally artifacts to copy to Bugzilla. The Users component must be specified. Multiple CopySelector tags are ANDed together. An individual selector specification has the form:
<field><relation><value>,
where:
   <field> is the name of a Bugzilla bug field
   <relation> is one of =, !=, gt, lt, gte, lte
   <value> is a valid value for the <field>
See FAQ for more details.
<CopySelector>
Status = Open
</CopySelector>
<CopySelector>
Priority = Low
</CopySelector>
<UpdateSelectors>    <UpdateSelector> Criteria to use when finding existing Rally artifacts to be updated in Bugzilla. The Users component must be specified. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
where:
   <field> is the name of a Bugzilla bug field
   <relation> is either = or !=
   <value> is a valid value for the <field>
See FAQ for more details.
<UpdateSelector>
Release != alpha
</UpdateSelector>
</RallyConnection>

Tip: Avoid special characters contained in a Rally workspace or project name that are markup sensitive. For example:

& ampersand becomes &amp;
> greater than becomes &gt;
< less than becomes &lt;

Example: Research & Development → Research &amp; Development

<BugzillaConnection>

Tag Name Description Sample Values
<Url>
Required
Bugzilla server name (or IP address) and port. Syntax is server:port. mybzserver:8080
<User>
Required
User to make the API requests to create and update entities in Bugzilla. myuser@company.com
<Password>
Required
Password for user to make the API request to create and update entities in Bugzilla. Note: The first time the connector runs, it will encode the password so it is not saved in plain text. mypassword
<ArtifactType>
Required
Entity name for the entities you want to create and update in Bugzilla. bug
<IDField>
Required
Bugzilla custom field used to store the unique ID of a bug, usually ID. id
<ExternalIDField>
Required
Bugzilla custom field (Free Text) that stores the unique ID for the Rally work item. See Create an External ID Custom Field in Bugzilla. cf_rally_field
<CrosslinkUrlField> Bugzilla custom field (Free Text) containing text of a hyperlink to the corresponding artifact in Rally. cf_rally_url
<CopySelectors>
   <CopySelector>
Criteria to use when finding new Bugzilla issues to copy to Rally. The Users component must be specified. Multiple criteria are ANDed together. An individual selector specification has the form:
<field><relation><value>,
where:
   <field> is the name of a Bugzilla bug field
   <relation> is one of =, !=, gt, lt, gte, lte
   <value> is a valid value for the <field>
See FAQ for more details.
<CopySelector>
status = Open
</CopySelector>
<CopySelector>
priority = Low
</CopySelector>
<UpdateSelectors>    <UpdateSelector> Criteria to use when finding existing Bugzilla issues to be updated in Rally. The Users component must be specified. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
where:
   <field> is the name of a Bugzilla bug field
   <relation> is either = or !=
   <value> is a valid value for the <field>
See FAQ for more details.
<UpdateSelector>
Release != alpha
</UpdateSelector>
<FieldDefaults> Set a default value for a Bugzilla field. <Field><Name>Bugzillafieldname</Name><Default>defaultvalue</Default></Field>
</BugzillaConnection>



<Connector>
Tag Name Description Sample Values
<FieldMapping>
Required
Determine what fields map between the two systems. See Field Mapping.
<OtherFieldHandlers>
   <OtherEnumFieldHandler>
Allows a user to map non-alike drop-down values between the two systems. See Map Drop-Down Values.
   <RallyConcatFieldHandler>
      <FieldName>
         Dest-fieldname
      </FieldName>
      <ConcatFields>
         <Field>Src-fieldname1</Field>
         <Field>Src-fieldname2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </RallyConcatFieldHandler>
Using the contents of Dest-fieldname as the initial string, appends each additional Src-fieldnameN to Dest-fieldname, using HTML break tags (<br />) to separate each additional field value.

Some custom field


Description
some other field
.....
   <RallyDateTimeFieldHandler>
      <FieldName>F1</FieldName>
      <DateTimeFormat>S1</...>
   </RallyDateTimeFieldHandler>
Bi-directional.
Rally to Other: Convert the Rally ISO date in field F1 into a date string formatted as specified by the string S1 (as per Ruby's DateTime.strftime function) and store this new date string into the field F1 is mapped to.
Other to Rally: The date string contained in the field which F1 is mapped to, is converted into a Rally ISO date (in accordance with (through Ruby's DateTime.parse) and stored in Rally's F1 field. Note that string S1 is not used in this case.

TestDate
%m-%d-%Y%H:%M:%S
   <RallyEnumFieldHandler>
      ....
   </RallyEnumFieldHandler>
Allows for the mapping of non-alike drop-down values between the two systems. See Map Drop-Down Values.
   <RallyReferenceFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyReferenceFieldHandler>
Used to map a field from an object.

User,Owner,Tester,...


Name,FormattedID,...
   <RallyUserEmailFieldHandler>
      <FieldName>Owner</FieldName>
   </RallyUserEmailFieldHandler>
Rally user to whom error and warning info will be emailed.
User,Owner,Tester,...
   <RallyUserFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyUserFieldHandler>
Used to map user names. See Map User Names.

User,Owner,Tester,...


Name,FormattedID,...
   <RallyCSVUserMappingFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <FileName>
         name-of-file
      </FileName>
   </RallyCSVUserMappingFieldHandler>
Specifies the name of a field being mapped (name-of-field) and a CSV file where user mappings are stored (name-of-file). The CSV file is used to lookup and transform usernames based on the mappings specified within. See a more detailed explanation on the FAQ page or an example XML file.

SubmittedBy


MyUserMappings.csv
</RallyFieldHandlers> (closing tag)  
<OtherFieldHandlers>
    <OtherEnumFieldHandler>
Allows you to map drop-down values for a field between systems. See Map Drop-Down Values.
</Connector>



<ConnectorRunner>
Tag Name Description Sample Values
<Preview> Enable a preview mode for testing where no objects are copied and updated in either system. false or true
<LogLevel> Determines what type of messages are written to the log file. The highest level is Debug where all messages are displayed. The default log level is Info. Fatal, Error, Warn, Info, Debug
<Services>
Required

Use the copy services to initially reflect items between systems, then use the update services to keep those reflected items up to date.

The alternative update service searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields into Rally. This allows changes done in both systems to not cause overwrites of old data.

Copy services:

COPY_JIRA_TO_RALLY
COPY_RALLY_TO_JIRA

Update services:

UPDATE_JIRA_TO_RALLY
UPDATE_RALLY_TO_JIRA

Alternative update service:

UPDATE_RALLYFIELDS_AND_OTHER (may not be used in conjunction with the other update services)

See FAQ for more information.

<Emailer>
   <Level>value</Level>
   <SendEmailFrom>value</SendEmailFrom>
   <SendEmailTo>value</SendEmailTo>
   <SMTPServer>value</SMTPServer>
   <SMTPPort>value</SMTPPort>
   <SMTPUser>value</SMTPUser>
   <SMTPPassword>value</SMTPPassword>
   <SMTPSec>value</SMTPSec>
</Emailer>
Opening tag for this feature.
Which logfile messages to email.








See example.
Error or Warning
monitor@acme.com
monitor@acme.com
smtp.acme.com
587
Username@Domain.com
Password
TLS
 
</ConnectorRunner>

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.

Run the connector

Once the bz_config.xml is set up, you can start running the connector. On Windows, if you installed the Rally for Bugzilla connector using the RallyforBugzillaConnector-x.x.x-yyy.exe, double-click on the startbz.bat file (customarily installed in C:\Program Files\RallyforBugzillaConnector\startbz.bat). This starts the connector in a DOS command window and opens 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 open a DOS shell and type:

ruby rally2_bz_connector.rb bz_config.xml

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 more information, see Multiple Configuration Files.

Troubleshoot 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> element in the <ConnectorRunner> section of the configuration file. For more information, see Managing the Logger and Log Files.

To see the most recent log messages on Windows, rename the file WinTail.dat to WinTail.exe, 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:

  • Connecting to Rally is successful
  • Connecting to the Bugzilla is successful
  • Fields in the field mapping section exist in Rally and in Bugzilla
  • 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.

Incorrectly mapped defect fields

By default, Bugzilla has certain required fields. When those fields are incorrectly mapped to a Rally defect, the connector gives the following warning:

[2014-01-29 21:05:16 Z] WARN : RallyEIF::WRK::BugzillaConnection.initialize - Exception Bugzilla error: You must select/enter a OS. detected trying to create Bugzilla bug.

There are two workarounds to resolve this issue:

  • Create a custom field in Rally and map it to the field in Bugzilla.
  • Create a field default to map those fields.

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

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

Attachments

Attachments are not supported by the Bugzilla connector.

Map releases and iterations with multiple projects

When using a <RallyReferenceHandler> to map releases and iterations with the same name and multiple projects, you may receive an error if the release or iteration you are updating on the defect references a different project than the defect is assigned. The connector only returns the first release or iteration with the matching name in Rally so it could have a reference to a release or iteration in a different project.

Newline characters

In Bugzilla text fields, the newline character is not supported. As a workaround, use <br>.

CrosslinkUrlField URL not suitable for some

When the connector is used to create a URL link in Rally (through <CrosslinkUrlField>) which is to reference the original Bugzilla bug, the URL stored is the RestAPI link. For instance, the full URL may look like this:
           http://bugzilla.myserver.com/bzapi/bugzilla/show_bug.cgi?id=123
when you may actually want something like:
           http://bugzilla.myserver.com/show_bug.cgi?id=123

Revision history

  • 4.4.4 - 03-Mar-2014
    • Enhancements/Fixes:
      • Added new RallyBugzillaCommentLinker so that there is no need to Map Rally Discussion with Bugzilla Comments.
      • Note: Mapping Rally discussions with Bugzilla comments will now throw the following error:
        [2014-02-07 20:35:18 Z] DEBUG : RallyEIF::WRK::Connector.block in map_fields_to_other -   Mapping Discussion(#<RallyAPI::RallyCollection:0x5da5240>) - to - comment(#<RallyAPI::RallyCollection:0x5da5240>)
  • 4.4.2 - 05-Feb-2014
    • Enhancements/Fixes:
      • Supports the latest 1.3 REST API
  • 4.3.0 - 16-Jan-2014
    • Enhancements:
      • Upgrade from Ruby 1.9.2-p290 to Ruby 2.0.0-p247
      • Performance improvement gained by using rally_api rather than rally_rest_api
      • Added more build tests
      • Added <SuppressDeprecationWarning> XML tag
      • Ensure the ExternalID is of type String or Integer (DE18560)
      • Connector would validate only the first config file on command line (DE17492)
      • Upgrade to version 1.42 of the WSAPI
    Note: For the 4.3.0 version of this connector, any custom code (such as a custom field handler) will require modifications. A working example can be found here (you must be logged into the Rally Support Community to view).
  • 2.8.8-125 - 14-Dec-2012
    • Enhancements:
      • Minor logging improvements
    • Fixes:
      • DE15642: Email notification of errors and warnings, in the <Emailer> feature, would not send email if the <Level> was set to Error
    • Known issues: (none)
  • 2.8.6-121 - 16-Oct-2012
    • Enhancements/Fixes:
      • Added artifact ID to message string
      • Added more debug output in Rally connection section
      • Improved performance by removing refresh on workspace read in find-workspace loop
      • Updated to rally_api 0.6.0 gem
    • Known issues: (none)
  • 2.8.1-120 - 25-Jul-2012
    • Enhancements/Fixes:
      • Fixed issue with Release names
      • Added <RallyKeyword2TagFieldHandler> and <RallyDateTimeFieldHandler>.
  • 2.7.4-107 - 13-May-2012
    • Enhancements/Fixes:
      • Added ability for FormattedID in OTHER system to have lower case prefix (us123) or upper case prefix (US123)
      • Added subfield specifications on CopySelectors from Rally using the precopy feature
      • Added mapping of flag fields
      • Added XML include capability so common text can be included as a separate file
English

Feedback

Please send us your feedback regarding our help site. For feedback regarding the Rally product, click here to open a support case or click here to submit a new feature request
English
By submitting this form, you accept the Mollom privacy policy.
© 2014 Rally Software Development Corp | Legal