YouTrack Server 2022.1 Help

Import from YouTrack

The new option to import data from YouTrack lets you migrate one or more projects from another YouTrack service.

In essence, an import configuration is a graphic UI representation of an import script. A setup wizard navigates you through the import configuration process, which covers standard issue settings in YouTrack. If your project has a custom set of fields for issues, you can use an option to directly edit a client YouTrack import script in YouTrack itself.

Import Details

Import script migrates data from the source YouTrack including projects, issues, comments, attachments, issue tags, issue links, work items, issue history, custom fields, users, and groups.

Here is the list of entities that are not imported from the source YouTrack to the target:

  • Reports

  • Dashboards

  • Agile boards

  • Work item types

Set up an Import from Another YouTrack Installation

Before you add a new import configuration, you need to create a personal access token that will grant access to the target project in the YouTrack source installation. Then you can use the token for authorization when setting up the import configuration in the target YouTrack.

Create a Permanent Token in YouTrack

To set up import of issues from another YouTrack, you must preliminary create a personal access token for the user account that you use to access the target project in the source YouTrack.

To create a Permanent Access Token in YouTrack, please follow the instructions in the YouTrack documentation.

The list of access tokens.

Please use at least the following minimal set of scopes for the token to import YouTrack issues:

  • YouTrack

  • YouTrack Administration

Configure an Import from YouTrack

To set up import from YouTrack:

  1. From the Administration menu, select Integrations > Imports.

  2. Click New import to open the setup dialog.

    New import dialog
  3. Select YouTrack.

  4. Configure the import settings:

    YouTrack import settings

    Setting

    Description

    URL

    The Base URL of the source YouTrack service. Please note that it must include the context at which the YouTrack service is mapped. That is, for a YouTrack Cloud instance without custom domain, the URL must include /youtrack.

    Username or Email

    A username or email for the user account in the source YouTrack instance with the access to the projects that you need to import.

    Token

    The permanent access token of the user account in the source YouTrack.

    If required by your YouTrack installation, enable the Use SSL key for client authentication option.

    When done, click Next.

  5. Select projects for import. For details, see Project Mapping.

    Confirm settings and start import.
  6. When done, click Start import.

    • If you chose to import a project into a new one, a project of the same name will be created in the target YouTrack with found issues, articles, comments, custom fields, and users.

    • If you chose to import a project into an existing one, the target project will be updated with new issues, articles, comments, custom fields, and users.

When you have set up an import project, it is shown in the imports list. To view configuration and import details, select an import configuration in the list.

Import configuration details

In the details sidebar, you see import status and details on the data that was imported. Click the Resume button in the toolbar, to explicitly start polling for changes and importing updates from the source YouTrack instance.

You can also download the import log file to study and investigate when needed.

Project Mapping

On the final step of the import setup, you have an option to select those projects that you want to import to the target YouTrack. You can also choose whether to create a new project for the import or import data into an existing project in YouTrack.

Project Mapping

To configure project mapping:

  1. Locate those projects that you want to import.

    Use the filter bar on the right to filter projects by name.

  2. Select the projects that you want to import. Check the box on the top of the list to import all projects available in the source YouTrack.

  3. Select a target project for each imported project.

    • When loading the list of source projects for mapping, YouTrack checks for existing target YouTrack projects with corresponding names. If it finds a project with the same name as the imported one, YouTrack suggests it as the target project.

    • If there is no existing project in the target YouTrack with the same name, YouTrack suggests creating a new one.

  4. If you want to change a target project, select another option from the corresponding dropdown on the list.

  5. When ready, click Start import.

Edit Import Settings

To edit an existing import configuration:

  1. From the Administration menu, select Integrations > Imports.

  2. In the list of configured imports, select the one you need to edit.

    Details sidebar
  3. In the right sidebar, click the Edit in the toolbar.

  4. While in the edit mode, change the import settings, including the connection settings.

    Edit import settings.
  5. When ready, click Resume import.

    • Your changes will be applied, and YouTrack will poll the source YouTrack project for the updates.

Delete the Import Configuration

To delete an existing import configuration:

  1. From the Administration menu, select Integrations > Imports.

  2. In the list of configured imports, select the one you need to delete.

    Details sidebar
  3. Click the trash icon in the main toolbar of the page, or the Delete button in the right details sidebar.

  4. In the shown dialog, confirm the operation by clicking Delete.

    Confirm delete operation
    • The current import settings are removed.

    • Projects, issues, users, and groups that are already imported remain in YouTrack.

Last modified: 06 July 2022