Importing Data from Bugzilla

Note: Before you begin, please backup your JIRA data.

1. In your Bugzilla system, run the Bugzilla 'Sanity Check' to ensure your data is error-free.
2. Make sure that the Bugzilla database you wish to import from is running on MySQL.
   
   
3. Download and install the MySQL JDBC driver into JIRA. To do this, download the MySQL Connector/J driver. The package contains a file "mysql-connector-java-xxx.jar". Copy this to the common/lib/ directory in JIRA Standalone, or equivalent "lib" directory in your app server. Restart JIRA so the driver is loaded.
4. In JIRA's default permission scheme (associated with newly imported projects), ensure that the 'Browse', 'Create' and 'Comment' permissions are granted to the group 'jira-users' (or a group with the 'JIRA Users' global permission).
5. Log in as a user with the 'JIRA System Administrators' global permission.

6. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:

   

7. On the panel on the left, under the title 'Import & Export', click 'External System Import'

   
8. The 'Import Data' page will be displayed. Select 'Bugzilla'.

9. You will now be prompted for connection details to Bugzilla's MySQL database:

   

   Set the JDBC URL, database username and password for your system. The JDBC URL is of the format:

   jdbc:mysql:host[:port]/databasename?parameters
   

   host is the server hosting JIRA, whose MySQL allows incoming TCP connections on port port (defaults to 3306). databasename is the MySQL database name (usually 'bugs').

   The database name, username and user password can usually be found in the 'localconfig' file in Bugzilla's root directory, or in /etc/bugzilla/.

10. Click 'Next >>' to advance to the project selection page. If you have got the connection details wrong, you may have to wait about 30s for the connection attempt to time out.

11. You will now be presented with a list of projects in Bugzilla:

    

    Select the projects you wish to import (even if there is only one — select it!), and set import options via the checkboxes (the default checkbox settings is correct for most users). Click 'Next >>' to proceed.

12. You will now be prompted to choose a project key (the per-project prefix to attach to bug keys), and a project lead for each project to be imported. Important: do not use dashes or numbers in the project key!

    

    Click 'Import' when you are done to start the import. As imports frequently take a long time, you can watch the logs as they are generated by clicking the 'watch logs in separate window' link. Logs are also sent to stdout, and will appear in your app server's log:

    Importing project(s) 'Xerces-P', 'Xindice', 'XmlCommons'
    2004-02-27 15:34:10,031 INFO [atlassian.jira.util.BugzillaImportBean] Importing Project: Xerces-P
    2004-02-27 15:34:10,052 INFO [atlassian.jira.util.BugzillaImportBean] Importing Project: XmlCommons
    2004-02-27 15:34:10,061 INFO [atlassian.jira.util.BugzillaImportBean] Importing Project: Xindice
    2004-02-27 15:34:10,069 INFO [atlassian.jira.util.BugzillaImportBean] 3 projects imported from Bugzilla.
    2004-02-27 15:34:10,069 INFO [atlassian.jira.util.BugzillaImportBean]
    
    Importing Versions from project 'Xerces-P', 'Xindice', 'XmlCommons'
    
    2004-02-27 15:34:10,071 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: 1.5.6
    2004-02-27 15:34:10,080 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: unspecified
    2004-02-27 15:34:10,087 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: SWIG-1.3
    2004-02-27 15:34:10,093 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: 1.3
    2004-02-27 15:34:10,098 INFO [atlassian.jira.util.BugzillaImportBean] Importing Version: 1.4
    ...
    2004-02-27 15:34:10,228 INFO [atlassian.jira.util.BugzillaImportBean] Importing Component: SWIG
    2004-02-27 15:34:10,292 INFO [atlassian.jira.util.BugzillaImportBean] Importing Component: Test Scripts
    2004-02-27 15:34:10,346 INFO [atlassian.jira.util.BugzillaImportBean] Importing Component: Documentation
    ...
    Importing Issues from project(s) 'Xerces-P', 'Xindice', 'XmlCommons'
    2004-02-27 15:34:11,341 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "All files
    need Apache license"
    2004-02-27 15:34:11,343 INFO [atlassian.jira.util.BugzillaImportBean] Importing User: 
    jason1@openinformatics.com
    2004-02-27 15:34:16,430 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "SEGV on:
    getAttributes() in list context"
    2004-02-27 15:34:16,545 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "Sample code 
    must be updated"
    2004-02-27 15:34:16,680 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "SWIG 1.3
    rohibits sub-classing of wrapped classes"
    2004-02-27 15:34:16,878 INFO [atlassian.jira.util.BugzillaImportBean] Importing Issue: "AttributeList in
    Perl is broken (can't get attributes)"
    2004-02-27 15:34:16,909 INFO [atlassian.jira.util.BugzillaImportBean] Importing User: dgrey@internap.com
    ....
    2004-02-27 15:35:09,364 INFO [atlassian.jira.util.BugzillaImportBean] Importing User: ilm@doc.ic.ac.uk
    2004-02-27 15:35:09,580 INFO [atlassian.jira.util.BugzillaImportBean] 144 issues imported from Bugzilla.
    2004-02-27 15:35:09,581 INFO [atlassian.jira.util.BugzillaImportBean]
    
    Importing Votes
    2004-02-27 15:35:09,747 INFO [atlassian.jira.util.BugzillaImportBean] 0 votes imported from Bugzilla.
    2004-02-27 15:35:09,748 INFO [atlassian.jira.util.BugzillaImportBean] Reindexing (this may take a while)...
    2004-02-27 15:35:11,282 WARN [jira.issue.index.AbstractDocument] Unable to index field 'created' from ANT-4
    with value: 0002-11-30 00:00:00.0
    2004-02-27 15:35:29,170 INFO [atlassian.jira.util.BugzillaImportBean]
    Import SUCCESS and took: 79142 ms.
    
    

    It does not matter if your browser window times out — the import will continue regardless.

13. Once completed, you will see the 'Import SUCCESS' message, either in the logs (as above) or on the subsequent page:

    

    Congratulations, you have successfully imported your Bugzilla projects into JIRA!

    If you have any questions or encounter any problems, please contact Atlassian.

It is possible to re-import a Bugzilla project, and have JIRA import only 'new' bugs not previously imported. This allows for a transition period in which the imported JIRA project can be trialled, but bugs still logged in Bugzilla need not be lost.

To import only new bugs, click the 'Import only new issues' checkbox in the importer.

The Bugzilla importer creates a 'Bugzilla ID' custom field for imported issues, linking back to the original Bugzilla bug URL.

If you intend to use this, you will need to configure the URL to Bugzilla in jira-application.properties. The custom field can also be made to display just the ID (unlinked) in jira-application.properties. If you don't need this custom field, delete it or hide it.

The custom field is searchable, so you can search for JIRA issues by their old Bugzilla ID. There is also a portlet which lets you search by Bugzilla ID:

The Bugzilla importer source code is available here (BugzillaImportBean.java). For some customisations you may wish to make, editing this source code is required, as described below. For users of JIRA Standalone, there is a mini build-system which you can use to quickly compile and test modifications.

Importing custom priorities, statuses and resolutions

Bugzilla has a standard set of priorities, statuses and resolutions, but these can be augmented with new ones by editing a Bugzilla config file ('localconfig'). If your Bugzilla has custom statuses, JIRA will set the status of affected imported issues to "Open", and log a message ("... defaulting to JIRA status Open"). For other unknown fields (priorities, resolutions) JIRA will just not set the field, which may cause problems later (eg. issues Resolved but without a resolution are listed as open in the standard filters).

To avoid problems, it is a good idea to check whether your Bugzilla uses any custom resolutions, statuses or priorities:

mysql> select distinct(priority) from bugs;
+----------+
| priority |
+----------+
| P2       | 
| P4       | 
| P3       | 
| P1       | 
+----------+
4 rows in set (0.00 sec)
mysql> select distinct(resolution) from bugs;
+------------+
| resolution |
+------------+
| FIXED      | 
| DUPLICATE  | 
| WONTFIX    | 
|            | 
| LATER      | 
| INVALID    | 
| WORKSFORME | 
| REMIND     | 
+------------+
8 rows in set (0.00 sec)
mysql> select distinct(bug_status) from bugs;
+-------------+
| bug_status  |
+-------------+
| RESOLVED    | 
| CLOSED      | 
| NEW         | 
| ASSIGNED    | 
| REOPENED    | 
| VERIFIED    | 
| UNCONFIRMED | 
+-------------+
7 rows in set (0.00 sec)

(the above are all standard). If your bugs use anything non-standard, you will need to edit the mappings in BugzillaImportBean.java:

        static
        {
            // bugzilla's priorities mapping to JIRA priorities
            priorityMap.put("blocker", "" + IssueFieldConstants.BLOCKER_PRIORITY_ID);
            priorityMap.put("critical", "" + IssueFieldConstants.CRITICAL_PRIORITY_ID);
            priorityMap.put("major", "" + IssueFieldConstants.MAJOR_PRIORITY_ID);
            priorityMap.put("normal", "" + IssueFieldConstants.MAJOR_PRIORITY_ID);
            priorityMap.put("enhancement", "" + IssueFieldConstants.MINOR_PRIORITY_ID);
            priorityMap.put("minor", "" + IssueFieldConstants.MINOR_PRIORITY_ID);
            priorityMap.put("trivial", "" + IssueFieldConstants.TRIVIAL_PRIORITY_ID);

            // bugzilla resolutions mapping to JIRA resolutions
            resolutionMap.put("", null);
            resolutionMap.put("FIXED", "" + IssueFieldConstants.FIXED_RESOLUTION_ID);
            resolutionMap.put("INVALID", "" + IssueFieldConstants.INCOMPLETE_RESOLUTION_ID);
            resolutionMap.put("WONTFIX", "" + IssueFieldConstants.WONTFIX_RESOLUTION_ID);
            resolutionMap.put("LATER", "" + IssueFieldConstants.WONTFIX_RESOLUTION_ID);
            resolutionMap.put("REMIND", "" + IssueFieldConstants.WONTFIX_RESOLUTION_ID);
            resolutionMap.put("DUPLICATE", "" + IssueFieldConstants.DUPLICATE_RESOLUTION_ID);
            resolutionMap.put("WORKSFORME", "" + IssueFieldConstants.CANNOTREPRODUCE_RESOLUTION_ID);
            resolutionMap.put("NEEDTESTCASE", "" + IssueFieldConstants.INCOMPLETE_RESOLUTION_ID);

            // bugzilla status mapping to JIRA status
            statusMap.put("UNCONFIRMED", "" + IssueFieldConstants.OPEN_STATUS_ID);
            statusMap.put("NEW", "" + IssueFieldConstants.OPEN_STATUS_ID);
            statusMap.put("ASSIGNED", "" + IssueFieldConstants.OPEN_STATUS_ID);
            statusMap.put("REOPENED", "" + IssueFieldConstants.REOPENED_STATUS_ID);
            statusMap.put("RESOLVED", "" + IssueFieldConstants.RESOLVED_STATUS_ID);
            statusMap.put("VERIFIED", "" + IssueFieldConstants.RESOLVED_STATUS_ID);
            statusMap.put("CLOSED", "" + IssueFieldConstants.CLOSED_STATUS_ID);

            // workflow Mappings
            wfStepMap.put("1", new Integer("1"));
            wfStepMap.put("2", new Integer("2"));
            wfStepMap.put("3", new Integer("3"));
            wfStepMap.put("4", new Integer("5"));
            wfStepMap.put("5", new Integer("4"));
            wfStepMap.put("6", new Integer("6"));

            wfStatusMap.put("1", "Open");
            wfStatusMap.put("3", "In Progress");
            wfStatusMap.put("4", "Reopened");
            wfStatusMap.put("5", "Resolved");
            wfStatusMap.put("6", "Closed");
        }
          

(Note: wfStepMap and wfStatusMap should usually not be touched, unless you are importing into project with a non-standard workflow).

Changing the imported username format

Bugzilla uses email addresses for usernames (eg. "joe@example.com"). You may wish to automatically strip everything after the '@' to form a shortened username ("joe"), or otherwise alter imported names (eg. read from a lookup table to conform to a company-wide standard). This requires editing the BugzillaImportBean source (see above). The relevant code to modify is included in BugzillaImportBean.java, but commented out:

    /**
     * Given a Bugzilla 'profile' user record, infer a JIRA username from it.
     * In Bugzilla your username is your email address, and this will become your JIRA username, unless this method
     * is overridden to implement a different scheme.
     */
    protected String getUsernameFromBugzillaProfile(ResultSet bugzillaProfileResultSet)
            throws SQLException
    {
        return TextUtils.noNull(bugzillaProfileResultSet.getString("login_name")).toLowerCase().trim();

        // Alternatively, use the first part ('joe' in 'joe@company.com')
//        String name = bugzillaProfileResultSet.getString("login_name");
//        name = TextUtils.noNull(name).trim();
//        int i = name.indexOf("@");
//        if (i != -1) name = name.substring(0, i);
//        return name;
     }