Space
The intelligent code collaboration platform
Space is pivoting to SpaceCode, focused on Git hosting and code reviews. Learn more →
Import Issues into Space
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 issuedescription:
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:
- 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) - 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:
assigneeMissingPolicy:replace-with-default
will replace unrecognized assignee value with Unassigned.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:
- Open your profile and choose Personal Tokens on the sidebar menu.
- Click New personal token.
- Give this token some name and check Full access. If you choose limited access, you’ll have to implicitly give it the ImportIssues permission.
- Copy the token and save it in a convenient place.
To get a token from YouTrack:
- Open your profile.
- Click the Hub account link that reads “Update personal information and manage logins“
- Go to the Authentication tab and click the New token button.
- Give this token some name and add YouTrack to the Scope field.
- 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.
Argument | Description |
---|---|
--youtrackServer and --spaceServer |
The URLs of your source and target instances. |
--spaceToken |
Your personal token that you created in Space |
--spaceProject |
The key of your target Space project. You can get the project key on the project Settings page, under the Info tab. |
--youtrackQuery |
A query in YouTrack format that selects the YouTrack issues you want to import. In our example we’re only importing unresolved issues from project ABC. |
--youtrackToken |
Your personal token from YouTrack. |
--assignee |
Maps the assignee in YouTrack to a member in Space. |
--status |
Maps an issue status in YouTrack to an issue status in Space. |
--updateExistingIssues |
Tells Space to update previously imported issues if the issues being imported match their external IDs. The alternative is --skipExistingIssues |
--replaceMissingAssignee |
Tells Space how to handle issues when the assignee is not recognized in Space. --replaceMissingAssignee sets the assignee field to Unassigned. --skipMissingAssignee will not import such issues. |
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!