Bugzilla Installation & User Guide

Print this topicEmail this topic

Connector downloads:

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.4.1. 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 2.0.0-p247 (at least; note 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

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 into Rally.

This makes the chances of overwrites of data highly unlikely. The only scenario where an overwrite might occur is if User1 made changes in Rally and User2 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.

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
  • Windows XP, Windows 7, Windows 2003/2008/2012 Server, or Linux
  • 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 2.0.0-p247 (at least; note 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 2.0.0-p247 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 2.0.0-p247 is installed in the C:\Ruby20 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 the contents of the zip file locally on your machine. The contents of the zip include these files:
    $ unzip -l RallyConnectorforBugzilla-Ruby-4.4.11-maintenance-106.zip Archive:  RallyConnectorforBugzilla-Ruby-4.4.11-maintenance-106.zip
      Length      Date    Time    Name
    ---------  ---------- -----   ----
            0  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/
         1689  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/bz_config.xml
            0  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/field_handlers/
         1967  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/field_handlers/my_custom_field_handler.rb
            0  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/gems/
        12800  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/gems/rally-bzapi-0.1.9.gem
        14848  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/gems/rallyeif-bz-4.4.10.gem
        62464  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/gems/rallyeif-wrk-0.5.4.gem
          491  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/install.sh
          134  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/rally_csv_user_mapping_sample.csv
         3027  2014-10-16 20:31   RallyConnectorforBugzilla-Ruby-4.4.10-master-89/README.linux.txt
    ---------                     -------
        97420                     11 files
    
    Note: For previous releases of the connectors, you would invoke the connector through a command line similar to "ruby rally2_bugzilla_connector.rb cfgfile.xml -1". However, with the 4.3.0 release, the "rally2_bugzilla_connector.rb " source file is no longer included in the installation directory. Instead, it is installed with a Ruby GEM into one of the Ruby GEM folders, and is accessible from the path environment variable. The new command to invoke the connector is "rally2_bugzilla_connector.rb cfgfile.xml -1".
  2. Run the installer from the extracted directory by entering:
    $ ./install.sh
    installing gem: ./rallyeif-wrk-0.5.4.gem
    Fetching: mini_portile-0.5.3.gem (100%)
    Successfully installed mini_portile-0.5.3
    Fetching: nokogiri-1.6.1.gem (100%)
    Building native extensions.  This could take a while...
    Successfully installed nokogiri-1.6.1
    Fetching: httpclient-2.4.0.gem (100%)
    Successfully installed httpclient-2.4.0
    Fetching: rally_api-1.1.2.gem (100%)
    Successfully installed rally_api-1.1.2
    Successfully installed rallyeif-wrk-0.5.4
    5 gems installed
    installing gem: ./rally-bzapi-0.1.9.gem
    Fetching: json-1.8.1.gem (100%)
    Building native extensions.  This could take a while...
    Successfully installed json-1.8.1
    Successfully installed rally-bzapi-0.1.9
    2 gems installed
    installing gem: ./rallyeif-bz-4.4.10.gem
    Fetching: xml-simple-1.1.2.gem (100%)
    Successfully installed xml-simple-1.1.2
    Fetching: mime-types-2.0.gem (100%)
    Successfully installed mime-types-2.0
    Successfully installed rallyeif-bz-4.4.10
    3 gems installed
  3. If using a proxy:
    gem install -y -p http://proxyhost:portnumber builder
  4. Answer yes to any questions about installing required dependencies.

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

Rally accesses fields from their Display Name, not their Name. Spaces and underscores are removed, for example, Example Field becomes ExampleField.

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. They are run in the order specified.

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 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.
<RallyFieldHandlers> (opening tag)  
   <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> (opening tag)  
   <OtherEnumFieldHandler>
      ....
   <OtherEnumFieldHandler>
Allows a user to map non-alike, drop-down values between the two systems. See Map Drop-Down Values.
</OtherFieldHandlers> (closing tag)  
<RelatedObjectLinkers> For more complex mappings of fields (like collections).  
    <RallyAttachmentLinker /> Used to copy attachments between Bugzilla and Rally (bi-directional). Can be used on any object which supports attachments (in Rally: tasks, defects, stories, and tests; in Bugzilla: any issue type with attachments).
    <RallyBugzillaCommentLinker /> Used to copy discussions or comments between Rally and Bugzilla.
WARNING: There is a known limitation with this feature. Once Rally discussions have been synced with Bugzilla comments, they should never be modified in Bugzilla. It will cause a recursive copy, back-and-forth between the two systems, with the discussions and comments growing with each iteration. This occurs because the connector compares the two sets of discussions and comments. If they are not identical, it assumes they need to be re-synced. However, Rally discussions are read-only (once they have been created), so an edited comment in Bugzilla is copied to Rally as a new discussion. At that point the discussions and comments between the two system will be out of sync again, and this loop will continue indefinitely
</RelatedObjectLinkers> (closing tag)  
</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_BUGZILLA_TO_RALLY
COPY_RALLY_TO_BUGZILLA

Update services:

UPDATE_BUGZILLA_TO_RALLY
UPDATE_RALLY_TO_BUGZILLA

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 processing proceeds.

Alternatively on Windows, you can open a DOS shell and type:

rally2_bugzilla_connector.exe cfgfile.xml -1

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.

Modify the logging parameters

The connector logs messages as it is processing into a rallylog.log file in the current working directory. By default, the maximum size of a log file is 5 MB and the log rotation is limited to 10 files. You can adjust the maximum size of the log file and adjust the maximum count of log files in the log rotation by specifying command line arguments for this.

The -s <integer> option pair can be used to specify the maximum size of the log file in MB increments (up to 100 MB). This can also be expressed as --max-log-file-size <integer>.

The -m <integer> option pair can be used to specify the maximum count of files in the log file rotation scheme. This can also be expressed as --max-log-files-count <integer>.

Example: To set the log file max size to 50 MB and the maximum log file rotation count to 20 files for a single invocation of the connector:

rally2_bugzilla_connector -s 50 -m 20 bz_config.xml -1

OR

rally2_bugzilla_connector --max-log-file-size 50 --max-log-files-count 20 bz_config.xml -1

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.

Map releases and iterations with multiple projects

When using a <RallyReferenceFieldHandler> 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

Mid-air collision

[2014-01-29 21:05:16 Z] ERROR : RallyEIF::WRK::BugzillaConnection.rescue in update_external_id_fields - Bugzilla error: Mid-air collision on update attempt for item with id: 20922, last_change_time of 2014-10-14T17:25:48Z.

Cause: Check the Bugzilla api configuration values and verify that the time zone field is using the correct time zone

Known limitations

  • The <BugzillaConnection> does not support the HTTPS protocol (HTTP only).

Known issues

  • Need for the <RallyReferenceFieldHandler> is, for the most part, deprecated. Prior to the 4.4.6 release, if multiple projects were specified in the config file Release or Iteration value was sometimes mapped incorrectly. By relocating some logic, that issue has been addressed as well as being able to handle the most common Rally Reference fields (Project, Release, Iteration) automatically without needing explicit notation in the configuration file. If the connector detects that are using a <RallyReferenceFieldHandler< for one of those aforementioned fields, the connector will emit a deprecation warning message into the log file and will not register the field handler as that logic is now handled automatically. The are some edge cases where the use of <RallyReferenceFieldHandler< may be necessary, for fields such as Parent, Child, WorkProject, Owner and other similar fields.

Revision history

  • 4.5.3-master-97 10-March-2015
    • Enhancements:
      • Updated to use Rally WSAPI v2.0.
      • Added a RallyBooleanFieldHandler.
    • Fixes:
      • Fixed issue in YetiEmailer where header item had leading spaces not accepted by some email servers.
  • 4.4.12-maintenance-118 22-January-2015
    • Enhancements:
      • Support added for a RallyReferenceAttributeLookupFieldHandler intended to be used primarily with Release and Iteration fields where the attribute used for the lookup is other than the 'Name'.
      • This release is likely to be the last for the 4.4.x line that uses Rally WSAPI 1.43.
  • 4.4.11-maintenance-106 20-November-2014
    • Enhancements:
      • Updated code to account for changes in how Rally handles attachment content (uses strict_encode64 / strict_decode64).
  • 4.4.10-master-89 16-Oct-2014
    • Enhancements:
      • Modified rallyeif-wrk core dependency on rally_api to 1.1.2 (that depends on httpclient 2.4.0) to address SSLv3 security issue.
      • Added support for command line arguments to specify log file max size and file count.
      • Added support for specifying the scheme (http or https) in the BugzillaConnection Url.
    • Known issues:
      • The "--version" flag, as well as the logfile, will report "4.4.10-88-master-...." instead of " 4.4.10-89-master-....".
  • 4.4.8-master-80 18-Sep-2014
    • Enhancements:
      • Improved semantic comparison of Rally boolean values to strings ('true' / 'false') should result in fewer unnecessary updates.
      • Improved semantic comparison of Rally decimal values to integers/strings (1.0 should equal 1 or "1") should result in fewer unnecessary updates.
      • Improved comparison of Rally User to user identifier from Bugzilla should result in fewer unnecessary updates.
  • 4.4.7-master-78 29-Aug-2014
    • Enhancements
      • Modifications to make parsing RevisionHistory Revision records more robust, especially the Notes field.
  • 4.4.6-master-76 - 03-Jul-2014
    • Enhancements/Fixes:
      • Deprecated the RallyReferenceFieldHandler for Project, Release and Iteration fields.
  • 4.4.4-master-62 - 15-Apr-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 (using the QC connector) can be found here.

        Previous method for doing requires:
        require 'yeti/field_handlers/other_field_handler'
        require 'rexml/document'

        class MyCustomFieldHandler < ....FieldHandler
          ....
        end
        New way of doing requires:
        require 'rallyeif/wrk/field_handlers/field_handler'

        module RallyEIF
          module WRK
            module FieldHandlers

              class MyCustomFieldHandler < ....FieldHandler
                # See example code in installation directory:
                # ./field_handlers/my_custom_field_handler.rb
              end
            end
          end
        end
    • 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

Need more help? The Rally Success Community is your one-stop shop for self-service and support. To submit feedback or cases to Rally Support, find answers, and collaborate with others, please join us at rallydev.force.com/answers.
© 2015 Rally Software Development Corp | Legal