Import Issues into Space

Yuri Ryzhoff

Here at Space we understand that migrating to a new tool can be a hard decision, even more so if you have to start fresh and leave all your valuable data behind. Not anymore!

When it comes to issue tracking, you can now switch to Space and take your issues with you. We added a dedicated API endpoint that allows you to import issues from an outside issue tracker like GitHub or JIRA into your project in Space. And if you’re using YouTrack, we have a ready-to-run script for you that will make your import task a breeze.

Under the hood: the Space API

Before we get to details, we suggest you check out this endpoint in the Space HTTP API Playground — the best place to explore a new API functionality.

Navigate to the playground:

and type Import Issues into the search field:

The endpoint accepts a number of parameters that correspond to the most important issue fields. With each issue you can import its Summary (Issue title), Status, Issue ID, as well as its Assignee and Description.

In its visual representation of request elements, the playground follows the Space SDK format, and shows you, in addition to arguments, object types such as ImportMetadata. The Space SDK is beyond our scope here, but it’s worth mentioning that if you’re serious about building applications that interact with Space, it can be of real help. You can learn more about it in our documentation.

Now let’s take a closer look at our endpoint. It accepts HTTP POST requests at the following URL:

https://mycompany.jetbrains.space/api/http/projects/{project}/planning/issues/import

where mycompany is the subdomain name of your Space organization and {project} is an identifier of the Space project into which you’re importing issues. Either a project ID or project key can be used:

key:MY-PROJECT-KEY
or
id:my-project-id

You can get the project key on the project Settings page, under the Info tab. Or use the HTTP API Playground to find the correct values.

Request

Issue data to import is submitted in the request body as a JSON object with nested key-value pairs.

In metadata with importSource you specify where your imported issues came from (e.g. Jira) so you can identify and manage them in your Space project later on.

The issues element includes an array of objects, where each object contains parameters for each imported issue:

• summary: The headline or the title of the issue
• description: The description of the issue.
• status: The issue status, such as Open, In progress.
• assignee: The person assigned to the issue. You can pass either a username (john.doe) or first and last names (John Doe)
• externalId: The issue’s ID in external source.
• externalName: An alias that you provide for the issue to display it in Space instead of external ID.
• externalURL: The issue’s full URL in the original tracker. Turns the issue’s external ID into a link in Space.

Here’s an example of a simple request:

curl 'https://mycompany.jetbrains.space/api/http/projects/key:ACME-PROJECT/planning/issues/import' 
-d '{
  "metadata": {
    "importSource": "Jira"
  },
  "issues": [
    {
      "summary": "This thing is broken",
      "status": "Open",
      "assignee": "travis.wickett",
      "externalId": "ABC-124"
    }
  ],
  "dryRun": false
}'
-H 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJz' 
-H 'Accept: application/json' 
-H 'Content-Type: application/json'
-X POST

Every issue imported into your Space project must have a unique externalId. So, for example, when you are importing issues from two different GitHub projects and the issues share the same IDs, you’ll have to replace these IDs in one of the sources before submitting them to Space. If you still want the original IDs shown in Space, you can pass them as the externalName value mentioned before.

What happens if you import issues with the same external IDs on top of the ones imported before? They will be skipped. That’s the default behavior, but you can easily change it to actually update previously imported issues.

Update imported issues

When updating imported issues, you will need to define the onExistsPolicy. Pass it the value update and the previously imported issues will be incrementally updated with the ones that match their IDs. This feature may come handy when you have to maintain issues across two different trackers and keep them in sync.

What if there are no such statuses or assignees in Space?

You may face a situation when the original (source) issues have statuses that are not found in your target Space project. Or the assignees you submit with issues can’t be recognized by Space because the user names do not match or even don’t exist. To deal with such cases you can pass assigneeMissingPolicy and statusMissingPolicy

Here is the options for missing statuses:

1. Specifying statusMissingPolicy:replace-with-default will replace unrecognized status value with the first status value of an Unresolved type set in your Space project (e.g. Open)
2. If you specify statusMissingPolicy:skip or don’t pass this argument whatsoever, the issues with unrecognized statuses will be skipped during the import.

There are similar options for missing assignees:

1. assigneeMissingPolicy:replace-with-default will replace unrecognized assignee value with Unassigned.
2. assigneeMissingPolicy:skip will not import the issue if it has unrecognized assignee.

Before actually importing issues into Space, we suggest you execute a test run by passing the argument dryRun:true. Space sends back a detailed report that can help you spot and resolve a potential problem.

Response

By default, Space returns a server message and three lists of imported issues:

• created
• updated
• skipped

with details for each entity.

You can filter responses by adding query parameters to the request.

For example

/api/http/projects/{project}/planning/issues/import?$fields=message

will return nothing but a server message, such as

"message": "Created 15 Updated 0 Skipped 1"

Authorization

To successfully execute the import, you need the ImportIssues permission. For detailed information and instruction, refer to our Authentication and Authorization docs.

Now that you know so much about this endpoint, you can try it out in the HTTP API Playground and then create a script or application for your real-world task. Also, check out our script for importing issues from YouTrack.

Import issues from YouTrack

The script we’ve prepared lets you import issues from a YouTrack instance (Standalone or inCloud) into a Space project.

For each issue, you can import its:

• Summary
• Description
• Status
• Assignee

The script can also convert YouTrack usernames to Space usernames if they don’t match, and lets you choose what should be done if submitted statuses or assignees are not recognized in Space.

We are making the script available as a Docker container which can be run with a number of arguments. It shouldn’t be a problem even if you’ve never used Docker before. Let’s walk you through.

Before you start

First of all, take a look at your projects in both trackers. Do the status types match? Are there any YouTrack users that don’t exist in your Space project? It pays to make some alignments beforehand, if possible, so less data will be replaced or skipped. While there is not much you can do about mismatched usernames (aside from mapping and replacing them during the import), you can, for example, add a status that exists in YouTrack but is missing in Space.

Next, make sure you have sufficient rights in the both projects, as the script will access them on your behalf. In your Space project you have to be a Project Admin, or have the Import Issues permission which is included with this role. In YouTrack, you need the Read permission across all issues you want to import. Generally, if you can see an issue and its fields, especially Status and Assignee, you can import it.

You also need authentication tokens from both Space and YouTrack. You will provide them as argument values when you run the script. You can skip the YouTrack token, but only if your issues are open to the public and can be viewed by any guest account.

To get a token from Space:

1. Open your profile and choose Personal Tokens on the sidebar menu.
2. Click New personal token.
3. Give this token some name and check Full access. If you choose limited access, you’ll have to implicitly give it the ImportIssues permission.
4. Copy the token and save it in a convenient place.

To get a token from YouTrack:

1. Open your profile.
2. Click the Hub account link that reads “Update personal information and manage logins“
3. Go to the Authentication tab and click the New token button.
4. Give this token some name and add YouTrack to the Scope field.
5. Copy the token and save it in a convenient place.

As a final preparation step, you need to get your Docker instance up and running. Have a look at the installation guide in case you don’t have it yet.

Running the script

The script is stored as a Docker image in a public registry at

public.registry.jetbrains.space/p/space/containers/space-issues-import:latest

and the code is as available to everyone on GitHub at

https://github.com/JetBrains/space-issues-import

You can run the image by executing a docker run command in your terminal. For example:

$ docker run public.registry.jetbrains.space/p/space/containers/space-issues-import:latest

--youtrackServer https://youtrack.jetbrains.com
--spaceServer http://mycompany.jetbrains.space
--spaceToken SPACETOKEN
--spaceProject key::MY-PROG
--youtrackQuery "project:ABC #Unresolved"
--youtrackToken YOUTRACKTOKEN  
--assignee "Bob Sanders::Robert.Sanders"
--status "in-progress::In Progress"
--updateExistingIssues
--replaceMissingStatus
--replaceMissingAssignee

Let’s go over the arguments. The first five of them are mandatory, the rest are optional.

To check if everything works as planned, you can first execute the script in a test mode by passing the --dryRun argument. No issues will be created in Space, but you’ll get a report you can examine.

These are the most important arguments. You can see the full list at https://github.com/JetBrains/space-issues-import#arguments or by running

$ docker run public.registry.jetbrains.space/p/space/containers/space-issues-import:latest --help

That’s all there is to it!

In case you’re interested in the inner workings, this script is written in Kotlin. We use the Youtrack REST client to fetch issues from YouTrack, Space SDK to upload issues to Space, and Ktor as an HTTP client.

You can use it as a template. We encourage you to customize it for your particular task.

View and manage imported issues

In Space, your imported issues can be easily distinguished from the rest:

To view the history of import transactions, navigate to the issues Settings page and choose the Import History tab.

Clicking on a transaction row will bring a list of issues imported during this transaction. In case something went wrong, you can undo the transaction: click the Delete icon and all issues will be removed.

Please keep in mind that this is work in progress. In our continuous effort to facilitate migration we plan to add more functionality, such as importing issues from GitHub and CSV files.

Try it out, and if you feel something is missing, let us know!

Subscribe to Space Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!