On this page:

Using the JIRA Importers Plugin

The JIRA Importers Plugin can import your bugs from Bugzilla. Version 1.3 of the JIRA Importers Plugin is compatible with Bugzilla 2.20 to 3.6.3. Users of older Bugzilla versions will need to first upgrade the Bugzilla database tables to a supported version, using Bugzilla's checksetup.pl script. The JIRA Importers Plugin requires your Bugzilla database to be MySQL or PostgreSQL.

For the very latest version of the JIRA Importers Plugin, please visit plugins.atlassian.com.

About importing from Bugzilla

The import process consists of:

1. Running the Import Wizard to configure the import process and save it into a configuration file. (Note that you can edit your configuration file later by by re-running the Import Wizard and providing the name of your existing configuration file.)
2. Configuring the connection from your JIRA server to the Bugzilla database.
3. Running the import using your saved configuration file. You will typically do this several times (e.g. once or more for tests, once for production).

These steps are described in more detail below.

During the import process, the following data is copied from the Bugzilla database into JIRA:

How to import from Bugzilla

1. Before you begin, please backup your JIRA data.
2. In your Bugzilla system, run the Bugzilla 'Sanity Check' to ensure your data is error-free.
3. In JIRA's default permission scheme (associated with newly created 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 ).
4. Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
5. 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.
6. On the panel on the left, under the title 'Import & Export', click 'External System Import - Beta!'. Then select 'Bugzilla'.
7. The 'Import issues from a Bugzilla installation' page will be displayed:
   Screenshot 1: the 'Import issues from a Bugzilla installation' page
   
8. If you don't yet have a configuration file (or if you want to create a new one, or update the one you have), click the 'Import Wizard' text link (not button) at the bottom of the page. This will guide you through creating a Configuration File:
   • Project Key Mappings: For each Bugzilla project that you wish to import into JIRA, select the JIRA 'Project category' (if applicable) and the JIRA 'Project key'.
     • To import into an existing JIRA project, type a project key (or project name) that already exists in JIRA.
       There is no warning or error message if you select an existing key (or existing project name with a different key). The importer will import issues to the project specified by the key (or project name).
     • To create a new JIRA project and import into it, type a project key that does not yet exist in JIRA.
       The JIRA 'Project key' will be the prefix for the IDs of all issues in the given project.
   • Custom Fields: If your Bugzilla system contains any custom fields, you can either choose the JIRA custom field to which they will be mapped, or choose to have the importer automatically create a new custom field(s) in JIRA.
     Regardless of whether you specify mapping, the importer will automatically create a JIRA custom field for each extra Bugzilla field, unless you un-check the'Create new custom fields' option on the final 'Import Data' screen (see Screenshot 2 below).
   • Field Value Mappings:
     • 'Priority' field — If you don't specify mappings, the importer will automatically create missing values in JIRA and will ensure that the issues are migrated with the correct priority (e.g. "Normal" in Bugzilla to newly-created "Normal" in JIRA).
     • Usernames — If you don't specify mapping, the importer will automatically map Bugzilla usernames to JIRA usernames (lowercase).
       Regardless of whether you specify mapping, JIRA will automatically create usernames for missing users unless you un-check the'Create new users' option on the final 'Import Data' screen (see Screenshot 2 below).
     • 'Status' field — It is mandatory to map the Bugzilla 'bug_status' field to specific values of the JIRA 'Status' field, as the JIRA 'Status' field is integral to JIRA workflow (to learn more, please see What is Workflow and Configuring Workflow).
     • 'Resolution' field — If you don't specify mapping, the importer will create corresponding Resolutions in JIRA instead of using the existing ones.
   • Link Types: To learn more about JIRA link types, please see Configuring Issue Linking.
9. Configure the connection details to your Bugzilla database as follows:
   • Bugzilla URL — the URL of your Bugzilla instance.
   • Specify credentials — tick this box to show/hide the Bugzilla Login and Bugzilla Password fields. Note that if your Bugzilla instance requires authentication and you don't specify credentials, Bugzilla "Big File" attachments will not be imported.
   • Bugzilla Login — the Bugzilla user to use during the import.
   • Bugzilla Password — the password of the Bugzilla user to use during the import.
   • Database URL — the location of the Bugzilla My SQL database server. Enter this in the following format:

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

     • host — the server hosting the Bugzilla MySQL database. You can specify which incoming TCP connections to allow by using the port parameter (defaults to 3306).
     • databasename — the name of the Bugzilla MySQL database (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/.
   • Database Login — the database user that JIRA will use to access the Bugzilla database.
     Ensure that this account can access your Bugzilla database from the machine where JIRA is running.
   • Database Password — the password of the database user that JIRA will use to access the Bugzilla database.
   • Driver Name — The fully qualified name of the base class of the JDBC driver to use.:
     • "com.mysql.jdbc.Driver" for MySQL.
     • "org.postgresql.Driver" for PostgreSQL.
10. The 'Import Data' page will be displayed:
    Screenshot 2: the 'Import Data' page
    
    • 'Create new users' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create new usernames for Bugzilla users who do not already exist in JIRA.
    • 'Create new versions' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create new versions for Bugzilla 'milestones' which do not already exist in JIRA.
    • 'Create new components' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create new components for Bugzilla components which do not already exist in JIRA.
    • 'Create new custom fields' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create custom fields for Bugzilla fields which do not have a corresponding field in JIRA.
    • 'Maximum issues and failues' — If you wish, specify a maximum number of failed issues after which the importer will stop. If you want the import to continue regardless of any failures, leave this field blank. If your Bugzilla instance has a large number of issues, it's generally a good idea to run first the importer on a limited number of issues (e.g. 100), then manually inspect the imported issues to confirm whether your configuration file was specified correctly. When the results are satisfactory, you can run the import with no limit.
11. The importer will display updates as the import progresses, then a success message when the import is complete.

Congratulations, you have successfully imported your Bugzilla projects into JIRA! If you have any questions or encounter any problems, please contact Atlassian support.

Using JIRA's Built-in Importer

JIRA can import your bugs from Bugzilla. Currently, the built-in importer is compatible with Bugzilla 2.20 and above. Users of older Bugzilla versions will need to first upgrade the database tables to a supported version with Bugzilla's checksetup.pl script.

The data from the Bugzilla database is appended to the existing data in JIRA. The tool imports the following data from the Bugzilla database:

How to import from Bugzilla

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 the MySQL database which 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.

Importing only new bugs (repeated imports)

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.

Searching by Bugzilla ID

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:

Importer Source code

The Bugzilla importer source code is available here. 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.

Common Customisations

Importing custom severities, statuses and resolutions

Bugzilla has a standard set of severities, 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 (severities, 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 severities:

mysql> select distinct(severity) from bugs;
+-------------+
| severity    |
+-------------+
| blocker     |
| critical    |
| enhancement |
| major       |
| minor       |
| normal      |
| trivial     |
+-------------+
7 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 severities 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;
     }