Migrate to Shortcut From Other Tools

If you were 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.

One convenient way to migrate them over to Shortcut 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:

  1. Navigate to Settings
  2. Click Import / Sync under Workspace Settings
  3. 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:

  1. Navigate to "All Issues"
  2. Filter to the Issues you would like to Import
  3. Select "Export">"CSV All Fields"
  4. 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: Label A;Label B;Label C

created_at The date the Story was created 

Format: yyyy/MM/dd HH:mm:ss

Example: 2023/03/18 15:44:18 

If empty or omitted, the created date will default to today’s date.

Future dates are not allowed.

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: yyyy/MM/dd HH:mm:ss

Example:2023/03/18 15:44:18

Future dates are not allowed.

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: yyyy/MM/dd HH:mm:ss

Example:2023/03/18 15:44:18

Future dates are not allowed.

tasks To-do items to add to the Story

String format for each item. Example:

[X] task 1;[ ] task 2

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.





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.


Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request