Import Issues

Currently Space offers the following solutions for importing issues from external issue trackers into your Space project:

To import issues from YouTrack, use a ready-to-run script.
To import from other sources (e.g. JIRA, GitHub), you can create your own script or application using our dedicated HTTP API endpoint.

Import issues from YouTrack

The script 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.

The script is publicly available as a Docker container and can be run with a number of arguments right from your terminal.

Preparation

There are a few things you need to do before running the script:

Projects. 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.

Permissions. 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.

Authentication. You 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:

On the top left, click your avatar then choose Preferences → Personal Tokens.
Click New personal token.
Give this token a distinctive 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.

Docker. You need a Docker instance installed and running on your machine. If you don't have it, refer to the installation guide.

Run the script

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

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 https://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

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.

Arguments

Argument	Description	Is required
`--youtrackServer`	The URL of your source YouTrack instance.	Required
`--spaceServer`	The URL of your target Space instance.	Required
`--spaceToken`	Your personal token that you have created in Space	Required
`--spaceProject`	The key of your target Space project. You can get the project key on the project Settings page, under the Info tab.	Required
`--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.	Required
`--youtrackToken`	Your personal token from YouTrack.	Optional
`--assignee`	Maps the assignee in YouTrack to a member in Space.	Optional
`--status`	Maps an issue status in YouTrack to an issue status in Space.	Optional
`--updateExistingIssues`	Tells Space to update previously imported issues if the issues being imported match their external IDs. The alternative is `--skipExistingIssues`	Optional
`--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.	Optional
`--batchSize`	The size of a batch with issues being sent to Space per request. Default: 50.	Optional
`--dryRun`	Run the script in a test mode, without actually creating issues.	Optional
`--help`	Show the list of arguments and exit	Optional

You can use this script as a template and customize it for your particular task. The code is as available to everyone on GitHub at https://github.com/JetBrains/space-issues-import

Import issues API

Space HTTP API has a special endpoint that can be used to import issues from external sources.

To create a scripts or an application for your import task, you can use Space SDK which includes a set of libraries and Space API client.

You can study and experiment with the Import issues endpoint in the Space API Playground.

Endpoint

POST /api/http/projects/{project}/planning/issues/import

where {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

id:my-project-id

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

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.

Request

Issue data fetched from an external source 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.

Missing or mismatched status types and assignees

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 usernames 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 instructions, refer to Authorize in Space

View and manage imported issues

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

To view the history of import transactions:

Open your project and select Issues from the sidebar.
On the Issues page, click the Settings button.
On the Settings page, choose the Import History button.

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 and all issues from this transaction will be removed.

Last modified: 28 March 2023