Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

About importing from Trac

JIRA ships with the JIRA Importers Plugin pre-installed, so that you can easily import your bugs from Trac.Version 2.6.1 or later of the JIRA Importers Plugin is compatible with Trac version 0.12.2.If you have an earlier version you can upgrade it via the Universal Plugin Manager.

On this page:

The import process converts Trac data as follows:

In Trac

In JIRA

Import Notes

Project Environment

Project

Each Trac Environment is imported as a JIRA project. You can either specify an existing JIRA project as the target, or the importer will automatically create a project for you at time of import.

Ticket Type

Issue Type

You can configure mapping of Trac Ticket Types to specific JIRA Issue Types.

Status

Status

You can configure mapping of specific Trac values to specific JIRA values.

Summary

Summary

 

Description

Description

 

Versions

Versions

Versions are imported from Trac (if you choose), and are set to the Un-Released and Un-Archived state.

Component

Components

You can choose to have the importer automatically create your Trac components in JIRA, or choose to have bugs imported into no component in JIRA.

Comments

Comments

 

Priority

Priority (or a custom field)

You can choose to map one of either the Trac Priority field or the Trac Severity field (see below) to the built-in JIRA Priority field, and the other to a custom field. (Alternatively, you can choose to map both the Trac Priority field and the Trac Severity field to JIRA custom fields.) When importing into the JIRA Priority field, you can configure mapping of specific Trac values to specific JIRA values.

Severity

Priority (or a custom field)

You can choose to map one of either the Trac Priority field or the Trac Severity field (see below) to the built-in JIRA Priority field, and the other to a custom field. (Alternatively, you can choose to map both the Trac Priority field and the Trac Severity field to JIRA custom fields.) When importing into the JIRA Priority field, you can configure mapping of specific Trac values to specific JIRA values.

Milestone

Milestone

JIRA will create this as a custom field.

Attachments

Attachments

Attachments are extracted from the Trac Environment and saved to disk. To specify the location on disk, see Configuring File Attachments.

Resolution

Resolution

You can configure mapping of specific Trac values to specific JIRA values.

CC

Watcher

 

Keywords

Labels

 

User

User

The importer will automatically create JIRA users for any Trac users who do not exist in JIRA.

  • Passwords from Trac are not imported. Users from Trac will need to get their passwords emailed to them.
  • If you are using External User Management, the import process will not be able to create JIRA users; instead, the importer will give you a list of any new users that need to be created. You will need to create the users in your external user repository before commencing the import.
  • If you have a user-limited license (e.g. personal license), and the number of required users is larger than the limit, then the import will be stopped. A page will be displayed showing a list of users that can't be created.

Other fields

Custom fields

If your Trac system contains any custom fields, you can choose to map them to specific JIRA custom fields. If your custom fields don't yet exist in JIRA, the importer can automatically create them for you.

How to import from Trac

First you will need to ZIP up the contents of your Trac environment

  1. Go to your Trac Environment.
  2. If you use SQLite(Trac default) PostgreSQL or MySQL database make sure your database URL saved in conf/trac.ini is also reachable from JIRA server (using localhost or unix socket won't work).
  3. ZIP contents of Trac Environment without any leading directories.

Import into JIRA

  1. Before you begin, please backup your JIRA data.
  2. Log in to JIRA as as a user with the 'JIRA Administrators' global permission.
  3. Select 'Administration' > 'System' > 'Import & Export' > 'External System Import' > 'Trac'.
  4. The 'Trac Import Wizard' page will be displayed.
    • If you don't have a configuration file (or to create a new one, or update the one you have), leave the 'Existing Configuration File' field blank and click 'Next'.
      Screenshot 1: the 'Trac Import Wizard' page
  5. Project Key Mappings: For each Trac project that you wish to import into a new JIRA project, select the JIRA 'Project category' (if applicable) and type in a unique JIRA 'Name' and 'Key'.
    • (info) The JIRA 'Project key' will be the prefix for the IDs of all issues in the given project.
    • To import into an existing JIRA project, type a project key and project name that already exists in JIRA.
  6. Custom Fields: If your Trac system contains any custom fields, you can either choose to import into an existing JIRA custom field or have the importer automatically create a new custom field in JIRA.
    (info) Regardless of whether you specify mapping, the importer will automatically create a JIRA custom field for each extra Trac field, unless you un-check the'Create new custom fields' option on the final 'Import Data' screen (see Screenshot 2 below).
  7. 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
    • Usernames — If you don't specify mapping, the importer will automatically map Trac usernames to JIRA usernames (lowercase).
      (info) 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.
    • 'Status' field — It is mandatory to map the Trac '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.
  8. The 'Import Data' page will be displayed:
    Screenshot 2: the 'Import Data' page

    • 'Create new users/versions' — Leave 'ON' to create new users/versions/custom fields that do not yet exist in JIRA. (This is the generally recommended setting for these options.) Only select 'OFF' if you do not want JIRA to automatically create these new items for you.
    • 'Create new users/versions/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 new versions for Trac 'milestones' which do not already exist in JIRA.
    • 'Maximum issues and failures' — 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 Trac 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.
  9. The importer will display updates as the import progresses, then a success message when the import is complete. You can download the import log if you wish.

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