Bringing the work your team has completed elsewhere has never been easier. With our Jira importer, your progress, history, insights, and all the wins you’ve made together elsewhere can now be imported directly into Shortcut.
We’ll work to improve every facet of this import process using your direct feedback and insights along the way. Ready to get started?
Before you begin
Preparing for the import will ensure a smooth process from start to finish. Here are some key things you'll need to complete this process:
- Admin (or Owner) status on Shortcut (Members cannot see the Import page in Shortcut)
- Admin status on Jira (used to generate auth keys and tokens)
- Confirmation that your data lives on Jira Cloud
- Please note that we now support importing from Jira Server via the CSV importer. Go here for more details.
And, while certainly not mandatory, it could be helpful to consider doing this optional step as well:
- Create any new Workflow States you might need to match current Workflow States in Jira to save time
Step 1: Import setup
- Select "Jira Cloud" from the import options to head to the next page. If you are importing from Jira Server, Select "JIRA Server" as an option to import as a CSV.
- Enter the email you use to log in to Jira. (This must match your Jira email that has Admin status)
- Enter your generated Authorization Token. This can be found in Jira: Account Settings -> Security -> Create and Manage API tokens
- Enter in your API Hostname. Example: youraccount.atlassian.net (make sure to remove the https:// if you're copying this link over)
- Enter in your Project Key. Learn about the Project Key and where to find it here.
Step 2: Map a Workflow
- Select a Workflow to house your Jira data. You can use the generated one, map to an existing Team, or select a new one that you may have made in the planning portion of this process.
- Receive the "Success!" confirmation that your data is ready to be imported, and hit Next: Map Story Types.
Step 3: Map Story Types
- Map your Jira issue types to Shortcut issue types (Chore, Bug, or Feature). We'll also apply a Label with the previous Jira issue type to help your team stay organized.
- Verify the data looks correct and hit Next.
Jira Epics will be imported as Shortcut Epics. Jira Subtasks will be imported as Shortcut Stories with a dependency on the parent Story from Jira.
Step 4: Map Workflow States
- Map your Jira Workflow States to existing Shortcut Workflow States. You can also add a new Workflow State if needed and return to this process.
- Make sure everything looks great and hit Next.
Step 5: Maps Users
- Map Jira users to existing Shortcut users. Jira users that are not mapped to existing Shortcut users will still retain history activity within your data and can be invited post-import.
- Click Finish Import
And that's it! You've completed importing your data from Jira!
After the Import
What's next? You can now directly check out the contents of the Project housing all of your Jira data, or invite any users that weren't mapped during the process.
Your imported data should be easy to identify around Shortcut by their new Labels. Head to the Labels page and view the newly created Labels that accompany the Jira data. You can also use our bulk Story editor to make large-scale changes on Labeled Stories.
Need to roll back this import and try again? That's easy, too! Head back to the Import screen within Shortcut and navigate to the Past Imports thread. From here, you can delete previous imports
Need to Run a Second Import?
Running a second import will create new stories for Jira tickets that have already imported, resulting in duplicates.
Another point.
There are a few of options to get those additional tickets into Shortcut as Stories:
- Create a new Jira project, move the new tickets there, then import just that project (this is the easiest option, but note that these won’t be in the proper project in Jira, if that matters.)
- Rollback the prior import completely and re-import to get the new stories (Note that this will cause any changes done on the Stories that were part of the prior import to be lost)
- Do a new full import into a different project, then move the net new stories to the correct project, followed by a deletion of the remaining duplicates - very manual or would require scripting!
- Create new Stories manually in Shortcut for the new tickets in Jira
Frequently Asked Questions
Mapping
| Does the importer tool maintain dependencies? | Yes; the importer tool will maintain the following Story relationships and dependencies: blocks, is blocked by, relates to. |
| How does Shortcut's Jira importer handle mapping to Teams and Iterations? |
The importer tool is able to map Jira Workflow States to Shortcut Workflow states. All imported Stories will have multiple labels indicating what their Jira fields previously were. As such, we recommend utilizing the Search and Bulk Edit features to bulk assign Stories to given Teams and Iterations. |
| Will Shortcut's Jira importer maintain links between Jira tickets and Confluence? |
The importer tool does not currently consider links to Confluence. If it is necessary to maintain this linkage, we recommend manually pasting the Confluence link into the description of the ticket prior to importing. |
| Do imported Stories retain their Jira ticket ID? | Imported Stories will be given a unique ID within Shortcut. However, they will have a label assigned to them indicating their previous Jira ticket ID. Additionally, utilizing the API, each imported Story will have an "external_ID" field that references back to its Jira ID. |
| Does the importer tool import Sprints? | Our importer tool does not currently support importing Sprints. You can import the associated tickets and associate them to the Iteration using the Bulk Edit capability. |
Import
| How long does the import take? |
The amount of time the import takes depends on the amount of information being imported. We recommend working in batches so that you do not encounter timeouts. Small imports can be completed in a matter of minutes, while larger imports can take up to an entire business day to complete. |
| Will text formatting carry over? |
As Jira does not utilize markdown, text formatting will not be maintained upon import. |
Post-Import
| How can I reorganize Stories once imported into Shortcut? | See "Editing (and Bulk Editing) Stories)" on Working with Stories. |
| If I have a Jira ticket ID, how do I find it in Shortcut? | Placing the Jira ticket ID in quotes within the Search bar should surface the Jira ticket. |
| Do git pull requests stay linked upon import? | Pull requests within Shortcut are based on Shortcut Story ID. As such, we recommend including branch names in the description of tickets to ensure that the information is imported. Branches may need to be manually restored upon import. |
Other
| Is Shortcut able to assist with a backup of Jira data? | No, data that lives in Jira is the responsibility of the customer. Shortcut can not guarantee backups of Jira data. |
Updated