Importing data from Pivotal Tracker

This import path has been deprecated and will be removed in Jira 8.4

In Jira 8.4, we will drop support for built-in importers that are dedicated to specific applications, including this one. You will still be able to import data to Jira, provided that you use the CSV or JSON format. For more info, see End of Support announcements.

The Jira Importers plugin, which is bundled with Jira, allows you to import data from Pivotal Tracker, a 'Software as a Service' (SaaS) issue tracker application.

(info) Our main website highlights some top reasons why people migrate from Pivotal Tracker to Jira. Version 2.5 or later of the Jira Importers Plugin is required.

On this page:

Preparing Pivotal Tracker for data import into Jira

In Pivotal Tracker, please ensure you have switched on Allow API Access in your Pivotal Project's Settings.

Running the Pivotal Tracker Import Wizard

Before you begin, please back up your Jira data.

  1. Log in to Jira as a user with the Jira Administrators global permission.
  2. Choose > System. Select Import & Export > External System Import to open the Import external projects page.
  3. Select Pivotal Tracker to open the Connect with Pivotal Tracker page.
  4. On the Connect with Pivotal Tracker page, specify the following:

    Pivotal Username or Email
    Specify the user account that Jira will use to access issues on your Pivotal Tracker site.
    Pivotal PasswordSpecify the password of the user (above).
    Map user names
    (in expanded Advanced tab)
    Select this checkbox if you want to modify the name details of Pivotal Tracker users (which would be associated with Pivotal Tracker issues) when these users are created in Jira.
    Use an existing configuration file
    (in expanded Advanced tab)
    Leave this 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 Pivotal Tracker and those in Jira.
    (info)  Note:
      • 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 Pivotal Tracker Import Wizard, Jira will create a configuration file which you can use for subsequent Pivotal Tracker imports (for re-use at this step of the Pivotal Tracker Import Wizard).
  5. Click the Next button to proceed to the Setup project mappings step of the Pivotal Tracker Import Wizard.
  6. On the Setup project mappings page, select which Pivotal Tracker projects you wish to import into Jira.
    (info) All Pivotal Tracker projects are selected by default, so clear the checkboxes under Import of the Pivotal Tracker projects you do not wish to import into Jira.
    For Pivotal Tracker projects you wish to import into Jira, click in Select a project  and then do either of the following:
    • Select Create New from the drop-down menu and in the resulting Add A New Project  dialog box, type the following:
      1. A new project Name.
      2. A new project Key.
        (info) This will be used as the prefix for all issue IDs in your Jira project.
      3. The Project Lead.
    • 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.
      (info) Only Jira projects that use the PT Workflow Scheme (which is created with your first Pivotal Tracker import into Jira) can be chosen from the Select a project list. The PT Workflow Scheme  consists of the:
      • PT Workflow — mapped to all standard issue types.
      • PT Subtask Workflow — mapped to Jira's sub-task issue type.
      (tick)  Tip:  If you have not yet performed a Pivotal Tracker import into Jira but you would like to import your Pivotal Tracker issues into an existing Jira project, consider doing the following:
      1. Use the Pivotal Tracker Import Wizard to import your issues into a new Jira project. Upon doing so, Jira will create the PT Workflow Scheme and PT Issue Type Scheme. The PT Issue Type Scheme consists of additional issue types that do not exist in a default Jira installation, such as Chore and Release.
      2. (Optional) Delete this project if you do not intend to use it any further.
      3. Apply the PT Workflow Scheme and PT Issue Type Scheme to the existing Jira project you want to import your Pivotal Tracker issues into. (See Defining a project for details.)
      4. Re-use the Pivotal Tracker Import Wizard to import your issues into this existing Jira project.
  7. Click the Next button to proceed to the Setup user mappings step of the Pivotal Tracker Import Wizard.
    (info) If you did not select Map user names option above, skip to step 8. (The Next button will not be available.)
  8. On the Setup user mappings step of the Pivotal Tracker Import Wizard, in the Target value in Jira field:
    • Specify the username of a Jira user to match Pivotal Tracker users to existing Jira users.
    • Leave blank to add the Pivotal Tracker user's name details 'as is'. The user's Full Name in Jira is derived from the Pivotal Tracker's username value and the Jira username is derived from this Full Name (made lower-case).
    • Specify the Full Name in Jira to change a Pivotal Tracker's user's name details. The Jira username is derived from this Full Name (made lower-case).
  9. Click the Begin Import button when you are ready to begin importing your Pivotal Tracker data into Jira. The importer will display updates as the import progresses, then a success message when the import is complete.
    (info)  Note:
    • If you experience problems with the import (or you are curious), click the download a detailed log link to reveal detailed information about the Pivotal Tracker Import Wizard process.
    • If you need to import data from another Pivotal Tracker project or site with the same (or similar) settings to what you used through this procedure, click the save the configuration link to download a Pivotal Tracker configuration file, which you can use at the first step of the Pivotal Tracker Import Wizard.

Congratulations, you have successfully imported your Pivotal Tracker project(s) into Jira! If you have any questions or encounter any problems, please contact Atlassian support.

Tips for importing Pivotal Tracker data into Jira fields

The import process converts Pivotal Tracker data as follows:

Pivotal Tracker


Import Notes



Each Pivotal Tracker project is imported into a new Jira project. You can optionally import into an existing project if you have used the importer before.



Pivotal Tracker story types are recreated in Jira.







Attachments are extracted from the Pivotal Tracker database and saved to disk. The dates and user attaching the attachments will be retained.



Jira will recreate the Pivotal Tracker workflow and statuses during import.



Pivotal Tracker labels with spaces are imported with underscores (Jira does not support spaces in labels).

Story ID

External issue ID and External issue URL

Jira will create these as custom fields.


Fix Version/s

Past iterations in Pivotal are imported as released versions in Jira.

Story Estimates

Story Points

Order of stories


You will need to configure this custom field in Jira after the import. If you are using Jira Software, you may wish to activate issue ranking. This can be done either before or after importing your Pivotal Tracker data.

Time Tracker

Time Tracking

If you use time tracking in Pivotal this data will be automatically imported into a new Jira issue type called 'Chore' with a Summary field value of "Placeholder for imported time tracking data".



The importer will automatically create Jira users for any Pivotal Tracker users who do not exist in Jira.

  • Passwords from Pivotal Tracker are not imported (as they are hashed in the database). Users from Pivotal Tracker 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.

User Roles

Project Roles

Viewer = User ; Member = Developers ; Owner = Administrators

Last modified on Jul 2, 2019

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.