Importing data from Trac
The JIRA Importers plugin, which is bundled with JIRA, allows you to import data from Trac from a compressed Trac environment.
Our main website highlights some top reasons why people migrate from Trac to JIRA. Version 2.6.1 or later of the JIRA Importers Plugin is compatible with Trac versions 0.12.2 to 1.0.1.
On this page:
Preparing Trac data for import into JIRA
Compress your Trac environment:
- Access your Trac environment.
- If you use SQLite (the Trac default), PostgreSQL or MySQL for your Trac database, ensure your database URL (defined in Trac's
conf/trac.inifile) is also reachable from JIRA server (using 'localhost' or a UNIX socket will not work). - Zip the contents of Trac Environment without any leading directories.
Running the Trac Import Wizard
Before you begin, please back up your JIRA data.
- Log in to JIRA as a user with the JIRA Administrators global permission.
- Select Administration > System > Import & Export > External System Import.
- Select Trac to open the Trac Import Wizard: Setup page.
- On the Trac Import Wizard: Setup page, select your compressed Trac environment file, which you prepared above.
- Leave the Use an existing configuration file checkbox cleared if you do not have a configuration file or if you want to create a new configuration file. Configuration files specify a mapping between fields in Trac and those in JIRA.
- If you select this option, you will be asked to specify an Existing Configuration File.
- If you do not select this option, then at the end of the Trac Import Wizard, JIRA will create a configuration file which you can use for subsequent Trac imports (for re-use at this step of the Trac Import Wizard).
- Click the Next button to proceed to the Setup project mappings step of the Trac Import Wizard.
- On the Setup project mappings page, select which Trac projects you wish to import into JIRA.
- Start typing the name (or key) of a project that already exists in JIRA or use the drop-down menu to select an existing JIRA project.
- Select Create New from the drop-down menu and in the resulting Add A New Project dialog box, type the following:
- A new project Name.
- A new project Key.
This will be used as the prefix for all issue IDs in your JIRA project. - The Project Lead.
- Click the Next button to proceed to the Setup custom fields step of the Trac Import Wizard.
This step will almost always appear because at least one Trac field is not likely match an existing JIRA field. - 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.
- 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).
- 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).
Regardless of whether you specify mapping, JIRA will automatically create usernames for missing users. - '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 Working with workflows and Managing your workflows).
- 'Resolution' field — If you don't specify mapping, the importer will create corresponding Resolutions in JIRA instead of using the existing ones.
- '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.
- 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.
Tips for importing Trac data into JIRA fields
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. |
| Ticket # | External Issue ID | The Trac Ticket number is captured in a JIRA custom field. The import is not designed to have the JIRA issue number match the Trac ticket number. |
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.
|
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. |