Were you using a different tool like Linear, ClickUp, PivotalTracker, Monday.com, Zenhub, etc.? You probably have tickets or issues you’d like to get into Shortcut.
Do you have multiple Workspaces and need to recreate Story data in another Workspace?
One convenient way to migrate them over to Shortcut or recreate Story data in a new Workspace is to place them in a CSV file so that it’s compatible with Shortcut’s CSV import tool.
Initiate Import Request
The import process is assisted by our friendly Support team. To bring up your interest, please follow the following steps inside Shortcut:
- Navigate to Settings
- Click Import / Sync under Workspace Settings
- Select the Tool you're coming from
This will open up the Help modal to allow you to send your interest in the CSV import tool to our Support team. We will get back to you shortly and share the CSV template needed to get started!
If seeking to Import from JIRA Server...
...Follow the Import Request flow above to begin the process and export the issues from your JIRA Server Instance that you want to import into your Shortcut Workspace by using the Search Function:
- Navigate to "All Issues"
- Filter to the Issues you would like to Import
- Select "Export">"CSV All Fields"
- Use the CSV template provided by our Support team to properly format your file to import in the preferred Shortcut Workspace.
CSV Template Formatting
Support will have reached out to you via email with a blank template in the format our system accepts. After you've exported your data as CSV from your existing tool, simply ensure that the data in the columns of our template match how Shortcut expects data. Here's a list of the field columns we accept via CSV, as well as their definitions and possible value/restrictions:
| Field | Content | Notes |
|---|---|---|
| name | Title of the Story |
Required field. 5,000 character limit |
| id | A reference on the story to an External ID. This can be used to help track the ID the story had in the source platform |
Numerical values only. |
| state | The state the Story currently resides in |
Required field This value can be mapped to an existing Shortcut state during import. |
| type | The type of Story that is being imported. Story types can be feature, bug, or chore |
Note: only feature, bug, or chore string values will import into shortcut as story types. Any other string value will default to feature story stype. |
| requester | The person who requested (e.g. created) the Story |
Email Address, Name, or username is acceptable. You will be able to map this user to an existing Shorcut user during or post-import. |
| owners | The name(s) of the user(s) who own the Story |
Email Address, Name, or username is acceptable. |
| description | The content that will be used to describe the Story |
20,000 character limit. Supports Markdown and light HTML. |
| labels | Tags that you can associate with your Stories |
Separate multiple labels by semi-colon Example: |
| created_at | The date the Story was created |
Format: Example: If empty or omitted, the created date will default to today’s date. |
| is_completed | Confirmation that the Story is done |
This is a boolean TRUE or FALSE field. |
| started_at | The date the Story was started |
Format: Example:
|
| epic | The name of the Epic the Story belongs to (Note: Stories do not map to existing Epics, a new Epic will be created) |
Alphanumeric value accepted. In Shortcut, Epics are a collection of stories that represent large initiatives. |
| epic_created_at | The time the Epic was created |
Format: Example:
|
| tasks | To-do items to add to the Story |
String format for each item. Example:
The X represents a completed task. |
At this time, the CSV import does not support Custom Fields, Teams, Objectives, or Iterations. However, these may be assigned post-import by bulk editing imported stories accordingly.
Here's an example of a filled-out template:
Click the image to enlarge
Send your completed CSV file back to Support, and we will start the import process for you!
Mapping Stories & Users During Import
Once you've sent Support your CSV file with the data filled as per the values outlined above, you're ready to go! Once support uploads the CSV file in the backend, you will be notified that the imported data is ready to be mapped via the bottom right corner once you log back into Shortcut:
Map to Existing Workflow and Workflow States
In the following screens, you will be able to choose which workflow and workflow states these stories will be imported into.
You can currently import the stories you provided in the CSV to a Single Workflow at a time. We recommend importing all stories into a workflow and then bulk-editing them into their correct workflow/workflow state afterward.
If you have a large number of stories that would make bulk editing unrealistic, we recommend sending Support a separate CSV file. You may then import the stories in their corresponding workflow and workflow states separately.
Map Imported Users to Existing Shortcut Users
The last step is to map the users you added to the requester or owner fields to existing Shortcut users.
If the user does not yet exist in Shortcut, we recommend first inviting them via Settings > Invite New Users. Then navigate back to Settings > Import / Sync > Past Import tab, and map the users there.
Success!
Once the import has been completed, your data is now in Shortcut!
We highly recommend bulk editing the Stories to move them and assign new Fields, Owners, etc. accordingly.
Updated