Importing From Pivotal Tracker to Shortcut

Recently, thousands of engineering teams learned that they would have to move off of Pivotal Tracker as their project management system. The announcement from Pivotal said that their “Startup” and “Standard” subscriptions will soon no longer be available for purchase and yearly auto-renewals will be cancelled. I’m sure this is a really unwelcome addition to those teams’ workload, and we’d like to help you find a new home here with us at Shortcut.

A lot of people don’t know this, but early on, our system actually evolved out of Pivotal Tracker and you can still see a lot of traces of that lineage in our system. There are a few differences of course, as we’ve evolved since those days - but we would love to help you feel right at home with us.

Of course, just as this was an unfortunate surprise for Pivotal’s customers, we hadn’t roadmapped building an import tool for customers migrating from Pivotal Tracker - certainly not one that covers the long tail of how your team might want to map Pivotal Tracker’s model onto our own. So what we’ve done is put some time into a lightweight, open source tool that ingests the CSV file that Pivotal Tracker exports, allows you to customize some of the mappings without any code changes, and exercises our public API to import your data into a Shortcut Workspace. I’d love to give you a quick overview of how to use it. This is largely the same material we have offered in the README.md of our Github repo of the importer, so if you’re anxious to get started, please head on over there and clone it! We've had several companies go through this to positive effect, and when folks have run into trouble we welcome your bug reports so that we can make it better.

Before I begin, please note that we wrote this quickly due to the urgent nature of your migration, so this should be considered Alpha software; we’re done with working on it, but that doesn’t mean it has all of the features or testing that we’d normally want to be able to offer to you as a finished product. We’ve done some testing (which you can see in the github repo) but as the README says, not only is it not guaranteed to be without bugs, but it has several known feature gaps to be filled before we consider it complete.

Using the Pivotal Tracker to Shortcut importer

1. Sign up for a Shortcut account.
   • NOTE: Do not run this importer against an existing Shortcut workspace that already has data you wish to keep.
2. Create a new Shortcut API token and export it into your environment.
3. Export your Pivotal project to CSV.
   • Unarchive the ZIP file provided by Pivotal and copy the primary CSV file to data/pivotal_export.csv
   • (Optional) To import your Pivotal story file attachments, ensure you included them when requesting your Pivotal export, and then copy the directories in your Pivotal export that are named after your Pivotal story IDs (which contain their file attachments) into the data/ folder of this project. This will result in a directory structure like data/10000/*, data/10001/*, etc.
4. Create/Invite all users you want to reference into your Shortcut workspace.
   • NOTE: If you're not on a Shortcut trial, please reach out to our support team before running this import to make sure you're not billed for users that you want to be disabled after import.
5. Run make import to perform a dry-run of the import.
   • Follow instructions printed to the console to ensure the mapping of Pivotal and Shortcut data is complete and correct.
   • You may edit the following files generated during initialization, to change how story priorities, story workflow states, and users are mapped between your Pivotal export and Shortcut workspace:
     • data/priorities.csv
     • data/states.csv
     • data/users.csv
   • This script will also write the following files during initialization to help you fill out the mapping files above:
     • data/shortcut_groups.csv is a listing of all your Shortcut Teams/Groups
     • data/shortcut_users.csv is a listing of all users in your Shortcut workspace
     • data/shortcut_imported_entities.csv contains a listing of all entities created during import
   • Ensure a group_id is set in your config.json file if you want to assign the epics and stories you import to a Shortcut Team/Group.
6. If the dry-run output looks correct, you can apply the import to your Shortcut workspace by running make import-apply
   • The console should print a link to an import-specific Shortcut label page that you can review to find all imported Stories and Epics.
   • If you run the importer multiple times, you can review all imported Stories and Epics by visiting Settings > Labels and then searching for the pivotal->shortcut label and clicking on it.
7. If you find that you need to adjust your configuration or your Pivotal data and try again, you can run make delete to review a dry-run and make delete-apply to actually delete the imported Shortcut epics and stories listed in data/shortcut_imported_entities.csv. You can also archive or delete content in the Shortcut application if needed.

Importer Limitations

There are some things that this importer does not do out of the box, although you are welcome to extend the importer in any way that works for you to deal with any of these issues as makes sense for your team:

• Story reviews: Shortcut does not have a feature equivalent to Pivotal story reviews, so they are imported as follows:
  • Pivotal story reviewers are imported as Shortcut story followers on the stories they were assigned for review. Shortcut story followers receive updates in their Shortcut Activity Feed for all story updates.
  • Imported stories that had Pivotal reviews have an additional comment with a table that lists all of the story reviews from Pivotal (reviewer, review type, and review status).
  • Imported stories that had Pivotal reviews have a label in Shortcut of pivotal-had-review.
• File attachments: Files included in the Pivotal export (and correctly placed in the data/ folder prior to import) are uploaded and associated with respective imported Shortcut stories. Other kinds of attachments (e.g., Google Drive) are not supported.
• Story blockers: Pivotal story blockers (the relationships between stories) are not imported.
• Epics: Imported epics are set to an unstarted "Todo" state.
• URL redirects: The URLs in the descriptions and comments of your Pivotal stories/epics are not rewritten to point to imported Shortcut stories/epics; they remain unchanged.
• Project History: Not imported into Shortcut.

Shortcut is a tool for software companies and engineering teams, so we targeted this tool at technical teams. If what we’ve done isn’t exactly what you want, the code is right there for your team to modify. If you run into a problem or a bug, we’re here to help. We wanted to put the ability to import your data into your hands as quickly as possible. We hope it’s helpful to you and we look forward to supporting your projects.

‍