Custom Bugzilla Importer for non-consecutive bug IDs

I have been recently working on extending the Rational Team Concert Bugzilla Importer functionality and I wanted to take some time to blog about it. Rational Team Concert provides an Import wizard to migrate Bugzilla Bug Reports to RTC. The details of such feature are described in this jazz.net article and this InfoCenter topic.

Update Feb 11 2013: I have updated the shared code to be able to ignore the Bugzilla bugs’ attachments.
The post content is the original one but you will find in the wizard the option to ignore the import of attachments, which may be useful when you are migrating old bugs information for traceability but you don’t want to carry all the attached files to your RTC database.

When it comes to importing bugs the feature allows you to specify the bugs in one of these ways:

  1. A single bug ID
  2. A range of bug IDs
  3. All bugs associated with a product in Bugzilla

Which you can specify using the Range section of the importer:

rangeBugs

I wanted to extend the functionality to allow specifying a set of non-consecutive bug IDs to be imported from a Bugzilla server. The sample code that I end up developing is quite simple based on leveraging the existing mechanics of the behavior, but it served me to understad how this feature works, which I want to share in this post.

In this post I am going to publish code, so our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license. Please also remember, as stated in the disclaimer, that this code comes with lack of promise or guarantee. In addition, let me point out that the code is based on the usage of internal API code, the general usage of such internal code is discouraged, and any code based on it may stop working in a future release without further notice.

You can download the code here. (code updated as of Feb 11 2013).

I am going to first go into the basic insights of the existing functionality building blocks I reviewed to implement this sample solution and briefly describe it. You can directly download the code and jump to the The extension in action section if you are not interested in such details for now.

Understanding the existing feature

My first attempt was to look in the Plain Java Client API for potential internal calls being used by the importer. However, it turned out that this feature is just implemented as a eclipse client side functionality. Of course you could write your own importer using the Plain Java Client API, but this would be a great effort for what I wanted to achieve, so I instead decided to dig into the implementation details of the Importer feature.

The Bugzilla Import wizard is part of “com.ibm.team.workitem.rcp.ui”; it is implemented as an extesion of “org.eclipse.ui.importWizards”, which makes it to contribute to the File > Import menu in Eclipse. You can find more information about the eclipse import wizards extension point in the Eclipse help here.

ImportMenu

The class com.ibm.team.workitem.rcp.ui.internal.wizards.bugzilla.ImportBugzillaMainPage implements the wizard page presented to the user to gather the required information and control the user input:

bugzillaImporterMainDefault

There are some interesting “pieces” for what I wanted to achieve, that interact once the user clicks Finish:

  • An instance of BugzillaConfiguration holds the configuration details being set for the import (like auth details), along with the destination project area and the mapping file, if any.
  • An instance of BugzillaNumberedRetrieval is created when you want to import a unique bug ID or range of IDs is used. The bugs are held in a structure of the form:
private ArrayList<String> bugNumbers= null;

Hmm, actually this was quite interesting to what I wanted to do. I want to feed a list such as that one with my “non-consecutive” list of bugs.

  • Finally the BugzillaImporter implements the import functionality. It gets a  BugzillaConfiguration instance with the configurtion details. The method we want to use for the import, “doImport”, expects as one of the parameters an IBugRetrievalStrategy implementor, such as the mentioned BugzillaNumberedRetrieval, which will hold the list of bugs that it has to import.

A sample solution

With the understanding of how range of bugs are specified in the user interface and treated under the covers, the first decission was how to gather my list of non-consecutive bug IDs. I decided that a CSV format would do the trick. From this point forward, and based on the information gathered from the existing functionality, the work was basically to decide how to gather such CSV list of bug IDs and make it available to the BugzillaImporter.

The extension skeleton

For gathering the list of bug IDs from the user, I thought of the following components:

A custom wizard that mirrors the existing one, implemented by the CustomBugzillaImportWizard class, which will therefore appear in the eclipse File > Import menu as well.

The wizard only page will be implemented by CustomBugzillaImportMainPage, which is a simplification of the existing wizard page, with the addition of two fields that will allow to specify the bugs records in two flavours:

  • A file with extenstion “.txt” or “.csv” (extension restricted by the wizard page implementation), containg the bugs IDs of interest.
  • A multiline text field that will allow the user to type a comma separated list of bugs to import.

importFields
We have the presentation to gather the required information, we have to parse it to make it available to the import functionality. This is based on two supporting classes:

A CustomBugzillaNumberedRetrieval class that extends BugzillaRetrieval will hold the list of bugs gathered from the CSV (whether the text field or a file). This class itself is really simple; I was just interested in storing the bug IDs to provide to the importer along with the expected methods to retrieve them:

public class CustomBugzillaNumberedRetrieval 
extends BugzillaRetrieval implements IBugRetrievalStrategy {

    private ArrayList<String> bugNumbers= null;

    public CustomBugzillaNumberedRetrieval(BugzillaConfiguration conf,
           ArrayList<String> bugNumbers) {
        super(conf);
        this.bugNumbers = bugNumbers;
    }

    public int getNumberOfBugs() 
    {
        return bugNumbers.size();
    }

    public Iterator<String> getIterator() throws BugzillaException
    {
        return bugNumbers.iterator();
    }
}

Update Feb 11 2013: A CustomBugzillaNumberedRetrievalNoAttach class has been added that will cause the attachments to be ignored in the import operation.

Now the responsibility to feeding the CustomBugzillaNumberedRetrieval relies on parsing the list of bug IDs. This is accomplished by the other supporting class called CustomBugzillaCSVTokenizer.  The parsing builds the list of bugs ignores wrong built IDs (i.e. the ones with characters), and is prepared to a smarter report of them building a list of wrong detected IDs as well.

PUTTING ALL TOGETHER

So in summary, the interaction of the elements work as follows:

  1. From CustomBugzillaImportWizard we gather the entered values from CustomBugzillaImportMainPage
  2. The configuration values are set in a configuration object (BugzillaConfiguration).
  3. The list of bug IDs is parsed via a CustomBugzillaCSVTokenizer object
  4. A CustomBugzillaNumberedRetrieval object is built with the list of IDs. Note that if the user has checked to do the import without attachments a CustomBugzillaNumberedRetrievalNoAttach object will be used instead.
  5. The rest of the code to call the importer functionality in CustomBugzillaImportWizard is nearly the same as the out-of-the-box BugzillaImportWizard for importing a range of bug IDs, but being fed by our custom built list.

The extension in action

How does this looks like from a user point of view? The extension has to be installed in the eclipse client. The provided sample code can be exported as a deployable plug-in and copied into the dropins folder so it will be installed at startup (<RTCEclipseInstall>/eclipse/dropins).

Once installed, it can be accessed from File > Import eclipse menu (or right-clicking and choosing Import…).

customImportMenu

In the wizard page the user just has to worry about deciding how he wants to specify the list of bugs, and type the usual parameters to connecting to the bugzilla server and the destination project area. A custom mapping file can also be added:

customPageFilled

Update Feb 11 2013: now you have also the option to specify to ignore the import of bugs’ attachments:

newUI

Clicking the Finish button will run the import process and, once finished, open the work items query result view with the list of work items created as resulf of the import.

importingCustom

Summary

The code in this post uses the existing features providing a wrapper that a allows to automate the import of random Bugzilla bugs to Rational Team Concert. The code can be enhanced and hardened but it currently can help in speeding up this migration effort task. The downloable assets are developed against the RTC 4.0.1 SDK, but the same code has been also tested with a 3.0.1 client.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s