JIRA is now available as three separate applications, JIRA Software, JIRA Service Desk, and JIRA Core. For more information on administering these applications, refer to the Administering JIRA Applications documentation.

Importing Data from Pivotal Tracker

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 product.

(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: If your JIRA installation has existing data — Back up your existing JIRA data.

  1. Log in to JIRA as 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.
    (tick)  Keyboard shortcut: g + g + start typing external system import
  3. Select the Import button associated with the Pivotal Tracker option 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 Password Specify the password of the user (above).
    Map user names
    (in expanded Advanced tab)
    Select this check box 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 check box 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 check boxes 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 dropdown 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 dropdown 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 Configuring 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

Story ID and Story 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 Agile, 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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

5 Archived comments

  1. User avatar

    Kishore Kandru

    I'm running into two issues when I try to import projects from Pivotal Tracker into Greenhopper.

    1. Though it creates a project and imports issues in it,It doesn't create a scrum board automatically for my project
    2. when I try to create a board for my imported project, it doesn't show any issues in it

    I need help with this import please.


    11 Jun 2013
  2. User avatar

    Wojciech Seliga

    Make sure that GreenHopper is enabled before starting the import. The importer should not complain on their first import screen about missing GreenHopper. We have recently fixed a bug in JIRA Importers Plugin (responsible for Pivotal Tracker import) where it incorrectly thought that GreenHopper is disabled/uninstalled. The new version with the fix will be available very soon. You can a workaround try: disabling JIRA Importers Plugin and GreenHopper, enabling Greenhopper first and then enabling JIRA Importers Plugin.

    Ad 2. does your JQL query match the issues you imported?

    If you have any problems with the import do not hesitate to raise a support request.

    13 Jun 2013
  3. User avatar

    Darshan Sawe

    At the moment it only imports new items. How do we force importing stories, so that it overwrites. Any workaround, if its not possible?

    18 Nov 2014
    1. User avatar

      Przemyslaw Borkowski [Atlassian]

      Importers by design import only new issues and unfortunately there's no way to overwrite (or update) existing issues via the Importer. However you can force it to create new issues. To do that you need to either:

      • remove value from "External Issue ID" custom field in any issue that you would like to import again
      • or perform the import to different project.
      18 Nov 2014
  4. User avatar

    Josh Williams

    How do you import when you signed up to pivotaltracker with Google OAuth?

    24 Jul 2015
Powered by Confluence and Scroll Viewport