If you have another issue tracker and are thinking about switching to JIRA, you can often easily migrate your existing data into JIRA with its built-in import tool.
In this recipe, we will look at importing data from Bitbucket's issue tracker. JIRA supports importing data from other issue trackers, such as Bugzilla and Mantis, and as we will see, the process is mostly identical.
Perform the following steps to import data from other issue trackers, such as Bitbucket, into JIRA:
- Navigate to Administration | System | External System Import.
- Select the source's issue tracker system. We will select Bitbucket for this recipe.
- Click on the Next button to authorize the JIRA importer to access data from Bitbucket, and when prompted, click on Authorize:
- Map projects from Bitbucket to JIRA projects. For those projects you do not want to import to JIRA, leave them selected with the Don't import this project option. Click on Next to continue.
After you have clicked on Next, JIRA will query Bitbucket to get an export of settings such as fields and values so that they can be used to map JIRA counterparts. This process may take a few minutes depending on the size of your Bitbucket project.
- Select the fields from Bitbucket that you want to manually map to the JIRA field values.
- Select the workflow scheme used by the target JIRA project so that we can map Bitbucket statuses to JIRA statuses in the next step. Click on Next to continue:
- Map the field values from Bitbucket to the field values of the JIRA fields as shown in the screenshot that follows. Click on Next to continue.
- Map Bitbucket's link types to the JIRA issue link types. Click on Begin Import to start importing data into JIRA:
- Review the import result. You can click on the download a detailed log link to get a full log of the process if the import has failed. You can also click on the save the configuration link to get a copy of the mapped files so that you do not have to remap everything from scratch the next time.
JIRA has a common wizard interface for all the different issue tracker importers. While each importer has its own uniqueness, they all follow the same basic steps, as outlined in the following list:
- Configuring the target data source: This is set to retrieve the target issue tracker's data. It can be a direct database access in the case of Bugzilla, or it can be over the Internet in the case of Bitbucket.
- Selecting a project to import to: This is where we have to choose issues that should be imported to either an existing project or a new project.
- Mapping target system fields to JIRA fields: This is where the target issue maps the tracker's fields to the corresponding JIRA fields. Custom fields can be automatically created as part of the process.
- Mapping a target system field values to JIRA field values: This maps the field data based on the previous field mappings. It is usually required for selecting list-based fields such as priority, issue status, and custom fields.
- Mapping the issue link types: This step is optional depending on whether the target issue tracker supports linking. If it does, those link types will need to be mapped to the JIRA issue link types.
Although the JIRA importer is able to handle most instances where the data mapping is straightforward, for bigger instances with complex mapping requirements, such as project merging and conditional mapping, it is recommended to engage an Atlassian Expert (https://www.atlassian.com/resources/experts) to handle the migration, rather than relying on the importer alone.
Other than the out-of-the-box supported issue trackers, there are other third-party add-ons that have support for other systems. For example, there is an add-on for importing issues from GitHub called JIRA GitHub Issue Importer, and you can get it from the following link:
https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugins.jira-importers-github-plugin
If there are no import options available for your issue tracker, you can also try to export your data in the CSV format and then use the built-in CSV importer to import the data. This is what we will discuss in the following recipe, Importing data from CSV.