Bugzilla Installation & User Guide

EOL Notice: CA Agile Central Bugzilla Integration will no longer be enhanced or fixed and technical support has been discontinued effective August 2015. Existing customers can continue to use the integration, but we encourage investigating other options that will keep your integration up-to-date.

The CA Agile Central connector for Bugzilla can synchronize multiple Bugzilla record types with many types of CA Agile Central artifacts. The CA Agile Central connector for Bugzilla allows customers to use CA Agile Central 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 CA Agile Central's project structure
  • Customize multiple extension points

The CA Agile Central 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 CA Agile Central 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 CA Agile Central 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 CA Agile Central and Bugzilla:

  • Copy bugs created in Bugzilla to CA Agile Central work items
  • Copy work items created in CA Agile Central to Bugzilla bugs
  • Update CA Agile Central work items based on changes made to Bugzilla bugs
  • Update Bugzilla bugs based on changes made to CA Agile Central work items

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

An alternative update service, UPDATE_RALLYFIELDS_AND_OTHER, searches CA Agile Central 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 CA Agile Central.

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

It is important to recognize that the data models of CA Agile Central 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:

System Setup

  • The following people will be involved in getting fields set up in both CA Agile Central and Bugzilla:
    • Bugzilla user with the ability to add fields to bugs
    • CA Agile Central user with administrator privileges for setup (only user access is needed to run the connector).
  • Consider the process you want to set up between CA Agile Central 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 CA Agile Central 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 CA Agile Central connector for Bugzilla:

  • A CA Agile Central 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/. Select 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 CA Agile Central 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

Download the Connector

To download the connector, follow the steps here.

Install the Connector

Pre-Installation Checklist

  • Access to a test environment and installation of Bugzilla with the Bugzilla REST API installed
  • CA Agile Central 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

Basic Installation Steps

  1. Install the connector (run the installer or extract the zip).
  2. Make configuration changes in CA Agile Central 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.

(Optional) If your site uses a proxy server to access CA Agile Central, 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. Select Advanced system settings.
  3. On System Properties, select Environment Variables.
  4. On Environment Variables, select 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. Select OK (three times) to save and exit this process.

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

Installation for Windows

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

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 Administration, Custom Fields.
  2. Select Add a new custom field.
  3. Enter a Name and Description.
  4. Select Free Text as the Type.
    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 CA Agile Central.
  5. Select Can be set on bug creation.
  6. Select 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: 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 CA Agile Central 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 CA Agile Central 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 CA Agile Central item. Use the same process in Bugzilla as for the CA Agile Central External ID. Note:

  • We suggest a field name of CA Agile CentralURL
  • 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

CA Agile Central Setup

CA Agile Central 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 CA Agile Central

  1. Log into CA Agile Central 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 , select Work Products & Fields in the sidebar and ensure the Work Product Type selected is Defect (or whichever work item you are mapping).
  5. Select 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 CA Agile Central, 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 CA Agile Central

It can be useful to have a clickable link in the CA Agile Central 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 CA Agile Central as for the CA Agile Central 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 .

                <WorkspaceName>Workspace Name</WorkspaceName>
                        <Project>Project Name 1</Project>
                <User>[email protected]</User>
        <!-- You can use an APIKey in place of User and Password tags -->
        <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey>
        <!--    <UpdateSelectors>
                        <UpdateSelector>state = Open</UpdateSelector>
                        <UpdateSelector>priority = High</UpdateSelector>

                <User>[email protected]</User>
        <!--    <CopySelectors>
                        <CopySelector>state = Open</CopySelector>
                        <CopySelector>severity = Low</CopySelector>
                        <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>

                <Services>UPDATE_BUGZILLA_TO_RALLY,  COPY_BUGZILLA_TO_RALLY</Services>

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 CA Agile Central, including CA Agile Central  URL, username and password or APIKey.

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

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 CA Agile Central 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 CA Agile Central 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 CA Agile Central. 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 CA Agile Central 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 CA Agile Central Description. Be careful when updating from CA Agile Central to Bugzilla, however, to compare the CA Agile Central Description with the concatenation of Bugzilla Comments and not create a new comment (containing the CA Agile Central Description, which is the whole comment history) each time the connector runs. Here again, mapping CA Agile Central Description to a custom Bugzilla field would be a better approach than creating new comments. CA Agile Central's Professional Services organization is available for this kind of custom development.

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.

Map Users

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

Map Bugzilla Keywords to CA Agile Central Tags

Example configuration file syntax for using the <RallyKeyword2TagFieldHandler>

                        <Field><Rally>Tags</Rally>  <Other>keywords</Other></Field>

Examples of supported and not-supported use:

  • Supported: Bugzilla to CA Agile Central:

    There are two keywords in Bugzilla, kw1 and kw2. The COPY_BUGZILLA_TO_RALLY and UPDATE_BUGZILLA_TO_RALLY service will create two new tags in CA Agile Central, kw1 and kw2.

  • Supported: CA Agile Central to Bugzilla:

    Create a new defect in CA Agile Central 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: CA Agile Central tags to non-existent keywords in Bugzilla:

    There are two tags in CA Agile Central, 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

Field Handlers

Map Drop-Down Values

Map User Names

Map Reference Fields From CA Agile Central (such as Project, Release)

XML Setup

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


Tag Name Description Sample Values
Server used to connect to CA Agile Central (excluding the HTTPS prefix, as the connector adds https:// to what is specified). sandbox.rallydev.com
Required if no APIKey specified
Login name for user to make the Web Services requests to create and update work items in CA Agile Central. [email protected]
Required if no APIKey specified
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
<APIKey> CA Agile Central APIKey (from CA Agile Central Application Manager) from the account to be used to access CA Agile Central from the connector. If this is specified, you do not need to supply a username and password. You do not need to whitelist the user associated with the value of the APIKey used as a value. ABC123plmokn43315...
Workspace in CA Agile Central you want to copy and update work items. My Workspace MyWorkspace
Contains a list of project tags. Each tag refers to one CA Agile Central project that will be used when finding new CA Agile Central work items to copy to the other system. For updating work items from CA Agile Central to the other system, all projects in <WorkspaceName> are considered. At least one CA Agile Central project must be specified in this tag. <Project>Rally1</Project>
Type of artifact you want to create and update in CA Agile Central. (Defect, defect),
(Story, UserStory, HierarchicalRequirement), TestCase
CA Agile Central 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 CA Agile Central. BugzillaID
<SuppressDeprecationWarning> Changes the WARN message about CA Agile Central WSAPI version deprecation in the logfile to an INFO message.
<CrosslinkUrlField> CA Agile Central custom field containing a hyperlink to the corresponding bug in Bugzilla. BugzillaLink
Criteria to use when finding new CA Agile Central 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> 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.
Status = Open
Priority = Low
<UpdateSelectors>    <UpdateSelector> Criteria to use when finding existing CA Agile Central 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>
   <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.
Release != alpha


Tip: Avoid special characters contained in a CA Agile Central 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


Tag Name Description Sample Values
Bugzilla server name (or IP address) and port. Syntax is server:port. mybzserver:8080
User to make the API requests to create and update entities in Bugzilla. [email protected]
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
Entity name for the entities you want to create and update in Bugzilla. bug
Bugzilla custom field used to store the unique ID of a bug, usually ID. id
Bugzilla custom field (Free Text) that stores the unique ID for the CA Agile Central 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 CA Agile Central. cf_rally_url
Criteria to use when finding new Bugzilla issues to copy to CA Agile Central. The Users component must be specified. Multiple criteria are ANDed together. An individual selector specification has the form:
   <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.
status = Open
priority = Low
<UpdateSelectors>    <UpdateSelector> Criteria to use when finding existing Bugzilla issues to be updated in CA Agile Central. The Users component must be specified. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
   <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.
Release != alpha
<FieldDefaults> Set a default value for a Bugzilla field. <Field><Name>Bugzillafieldname</Name><Default>defaultvalue</Default></Field>



Tag Name Description Sample Values
Determine what fields map between the two systems. See Field Mapping.
<RallyFieldHandlers> (opening tag)  
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

some other field
CA Agile Central to Other: Convert the CA Agile Central 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 CA Agile Central: The date string contained in the field which F1 is mapped to, is converted into a CA Agile Central ISO date (in accordance with (through Ruby's DateTime.parse) and stored in CA Agile Central's F1 field. Note that string S1 is not used in this case.

Allows for the mapping of non-alike drop-down values between the two systems. See Map Drop-Down Values.
Used to map a field from an object.


      <FieldName> Owner </FieldName>
CA Agile Central user to whom error and warning info will be emailed.
Used to map user names. See Map User Names.


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.


</RallyFieldHandlers> (closing tag)  
<OtherFieldHandlers> (opening tag)  
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 CA Agile Central (bi-directional). Can be used on any object which supports attachments (in CA Agile Central: tasks, defects, stories, and tests; in Bugzilla: any issue type with attachments).
    <RallyBugzillaCommentLinker /> Used to copy discussions or comments between CA Agile Central and Bugzilla.
WARNING: There is a known limitation with this feature. Once CA Agile Central 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, CA Agile Central discussions are read-only (once they have been created), so an edited comment in Bugzilla is copied to CA Agile Central 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)  



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

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 CA Agile Central 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 CA Agile Central. This allows changes done in both systems to not cause overwrites of old data.

Copy services:


Update services:


Alternative update service:

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

See FAQ for more information.

Opening tag for this feature.
Which logfile messages to email.

To send email to multiple emails use a semi-colon to delimit each email address.

See example.
Error or Warning
[email protected]
[email protected]
[email protected]


Note: Incrementally set up the connector. Start with a basic configuration file, test that you can connect to Bugzilla and CA Agile Central 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 CA Agile Central 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.

Credential Encryption (Added May 2015)

As of version 4.6.0 of the Connector, credentials occurring in the *Connection sections of the configuration file that are in clear-text are encrypted after the initial run using that configuration file. Credentials are identified as any configuration item tag appearing in a *Connection section whose name is '*User', or any '*Password' or 'APIKey'.

Credentials in the Emailer section (SMTPUser and SMTPPassword) will still be encoded. The credential encryption is localized for the installation of the connector and various aspects of the configuration file.

In practice, as long as the installation and execution folders are constant and the key CA Agile Central parameters in the configuration do not change, you are free to modify most of the contents of the configuration file without having to reset the credentials to their clear-text values. However, care must be taken in environments that do not have such stable characteristics to frequently check the log files for any entries that indicate environmental changes have taken place that prevent the connector from decrypting the encrypted values for use in the connector execution.

Note: The -c option can be used to specify leaving the password in clear case (if it is already in clear text) instead of encrypting. The command line for running the connector will be as follows ca_agile_central2_bz_connector.exe -c configfile.xml. The -1 option may still be used at the end of the command if needed.

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 


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 CA Agile Central is successful
  • Connecting to the Bugzilla is successful
  • Fields in the field mapping section exist in CA Agile Central 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 CA Agile Central 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 CA Agile Central 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 CA Agile Central Support.

Map CA Agile Central Projects

If you are copying defects from Bugzilla to CA Agile Central using the <RallyReferenceFieldHandler> with projects, you may see a Could not find CA Agile Central Project with name error in the log file if the connector user does not have editor permissions to that project in CA Agile Central.

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 CA Agile Central 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 CA Agile Central (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:
when you may actually want something like:

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

Troubleshooting Bugzilla API Configuration/Setup Issues

This link details some setup and configuration information for Bugzilla API Troubleshooting Bugzilla API Configuration/Setup issues.

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 configuration 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 CA Agile Central 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.6.5-master-112 24-November 2015
    • Enhancements:
      • Detecting duplicate CA Agile Central project names will now create an error log and exit condition.
      • Emailer functionality is now process prioritized to allow alert emails to send even if subsequent configuration validation fails.
      • Enhanced credential value encryption.
  • 4.6.4-master-111 16-November 2015
    • Enhancements:
      • Brand redesign.
  • 4.6.2-master-109 14-August 2015
    • Fixes:
      • Cleaned up log errors when the pre_copy method called on copy_to_rally cannot satisfy the necessary conditions which typically related to missing required fields or fields with a null/blank value.
      • XML include files containing CA Agile Central Url or Workspace or Project handled properly both before and after credential encryption.
  • 4.6.0-master-106 31-May-2015
    • Enhancements:
      • Credentials in the RallyConnection and BugZillaConnection sections are now encrypted.
  • 4.5.5-master-101 25-April-2015
    • Enhancements:
      • Support for using APIKey in place of CA Agile Central username and password
      • Better handling of FieldDefaults and values
      • Better logging of failed attempt to copy/update item from an other system to CA Agile Central
    • Known issues:
      Note: Copying CA Agile Central Tags to Bugzilla Keywords will now throw the following error: 
      [2015-05-12 17:00:28 Z] ERROR : RallyEIF::WRK::Connector.rescue in copy_to_other - Unable to create a Bugzilla bug with these field values: {:op_sys=>"All", :product=>"TestProduct", :platform=>"PC", :component=>"Component1", :version=>"v1", :summary=>"Bugzilla test for Keyword to Tags issue check 2", :status=>"NEW", :keywords=>["Testtag1"], :cf_rally_id=>"35478519604"}, Exception Bugzilla error: Expired, cancelled or otherwise invalid token detected trying to create Bugzilla bug
      • DE24588 - The "RallyKeyword2TagFieldHandler" errors when copying Tags from CA Agile Central to Keywords in Bugzilla even when the Keywords are already present Bugzilla
  • 4.5.4-master-98 2-April-2015
    • Enhancements:
      • Better logging for create/update operations when error conditions encountered.
      • Better handling of string fields mapped to CA Agile Central Name, Description, Notes that contain non-ASCII characters.
  • 4.5.3-master-97 10-March-2015
    • Enhancements:
      • Updated to use CA Agile Central 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 CA Agile Central WSAPI 1.43.
  • 4.4.11-maintenance-106 20-November-2014
    • Enhancements:
      • Updated code to account for changes in how CA Agile Central 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 CA Agile Central boolean values to strings ('true' / 'false') should result in fewer unnecessary updates.
      • Improved semantic comparison of CA Agile Central decimal values to integers/strings (1.0 should equal 1 or "1") should result in fewer unnecessary updates.
      • Improved comparison of CA Agile Central 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:
      Note: Mapping CA Agile Central 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>)
      • Added new RallyBugzillaCommentLinker so that there is no need to Map CA Agile Central Discussion with Bugzilla Comments.
  • 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 configuration 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

        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
    • 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 CA Agile Central 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 CA Agile Central using the precopy feature
        • Added mapping of flag fields
        • Added XML include capability so common text can be included as a separate file


Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.