YouTrack Server
 
2019.2
Get YouTrack Standalone
You are viewing the documentation for an earlier version of YouTrack Server. View this page in the current documentation
  1. Migrate to YouTrack
  2. Import Issues from Another YouTrack Server

Import Issues from Another YouTrack Server

Last modified: 17 December 2019

This page provides instructions for importing issues from one YouTrack server to another with a Python import script. Use these instructions to:

Before you begin, consider your options. Follow these instructions only when you want to migrate a limited number of projects or issues. If you simply want to move a YouTrack Standalone installation from one server to another, you can configure your new YouTrack server to use a copy of your old database. For instructions, see Change Database Location.

This procedure requires the following steps:

  1. Set up your local environment.

  2. Import your issues. You can either import all issues from a project or import single issues.

Permissions

The user account that you use to log in to the source YouTrack server requires permission to read issues and all their attributes including custom fields in the project to be imported. The user account that you use to log into the target YouTrack server requires permission to create and update a project, create users, read issue private fields, and update issue private fields. We recommend that you use an account with a System Admin role for both source and target servers.

Import Details

When you import issues from another YouTrack server, be aware of the following mechanics:

  • Issues are imported on a per-project basis. The source project is specified by its projectID. When issues are imported, all of the entities that are referenced in issue attributes are imported as well. This includes users (from issue fields like Reporter and Assignee) and sets of values for custom fields.

    warning

    References to users in the imported data are mapped to existing accounts in YouTrack. If a match is not found, a new user account is created.

    Imported users are allocated a license according to your subscription plan. For users that exceed your per-user license limit, the imported users are flagged as banned.

    For more information, see Ban User Accounts.

  • When a user is imported, the user account is assigned a randomly-generated password. To log in to the target YouTrack server with credentials from the source server, users must use the Reset password link to create a new password.

  • Only custom fields that are used in the target project are imported from the source YouTrack server. To make sure that you import all of the data from the source server, check the project in the target server and verify that it contains the correct number and type of custom fields.

Set Up Your Environment

Import to YouTrack is supported with Python import scripts. These scripts are built on top of the YouTrack REST API. You won't actually need to do any programming in Python, but you do need to install Python and the package that contains the import scripts.

To set up your environment:

  1. Download and install Python. The Python Client Library is compatible with Python 2.7+. Python 3 releases are not supported. You can choose whichever installation directory you prefer.

    The latest versions of macOS, CentOS, Red Hat Enterprise Linux (RHEL), and Ubuntu come with Python 2.7 out of the box. If you're working with any of these operating systems, continue with the next step.

  2. Install the package that contains the import scripts. Open the command-line interface that is supported by your operating system and enter the following command: 

    pip install youtrack-scripts

    • The import scripts are installed in your local environment.

    • The youtrack package that contains the Python client library for the YouTrack REST API is installed automatically as a dependency.

    If you prefer not to install the packages globally, you can install them for your user account only with the command: 

    pip install --user youtrack-scripts

Import All Issues in a Project

The Python script lets you import all issues from a source project at once. The target project is created automatically.

If you only want to import single issues, see Import Single Issues.

To import all issues in a project:

tip

This procedure requires multiple permissions. Use an account that is granted the System Admin role for both source and target servers.

  1. Open the command-line interface that is supported by your operating system.

  2. If necessary, change the current directory to the installation directory for Python. For example (Windows): 

    cd C:\Python27

  3. Enter the following command:

    youtrack2youtrack [OPTIONS] AUTH_OPTIONS source_url target_url [projectId ...]

    note

    The latest version of the import script supports authentication in YouTrack services with either permanent token or password. We strongly recommend using permanent tokens. Also, please note that the syntax for providing authentication data has changed. Now you must provide them as command options.

    Replace the command-line parameters with values as described here:

    Parameter

    Description

    source_url

    The URL of the source YouTrack server to import issues from.

    target_url

    The URL of the target YouTrack server to import issues to.

    projectId

    The projectID of the project to import to the target YouTrack server.

    The command also supports the following options:

    Option

    Description

    AUTH_OPTIONS - Use these to provide authentication data for source and target YouTrack services.

    -t

    Authorization token for the source YouTrack service.

    -u

    User login for the source YouTrack service.

    -p

    User password for the source YouTrack service.

    -T

    The authorization token for the target YouTrack service.

    -U

    User login for the target YouTrack service.

    -P

    User password for the target YouTrack service.

    OPTIONS
    -h

    Show the command help and exit.

    -a

    Import only attachments.

    -n

    Create new issues instead of importing them.

    -c

    Add new comments to target issues.

    -f

    Sync custom field values.

    -S

    Sync issue tags. Issue tags are created on behalf of the logged in user.

    -r

    Replace old attachments with new ones (remove and re-import).

    -d

    Disable users caching.

    -w

    Covert period values (used as workaround for JT-19362).

    -s

    Time Tracking settings in the format "days_in_a_week:hours_in_a_day"

    • The command executes the Python import script.

    • If successful, the following line is printed in the command-line interface for each issue: 

      Issue [ <issue ID> ] imported successfully

  4. Check the target YouTrack server and verify that the issues are imported correctly. If you are not satisfied with the results and want to re-import the data:

    • Delete the project in the target server. All of its issues are deleted as well.

    • Run the import script again.

Import Single Issues

In some situations, you might want to import issues one at a time. For example, when you want to migrate an issue from an internal YouTrack instance to your public tracker. The Python script used in this procedure imports a single issue from a source project to an existing project in another YouTrack server.

Follow these steps to import single issues from one YouTrack instance to another.

To import a single issue from one YouTrack instance to another:

tip

This procedure requires multiple permissions. Use an account that is granted the System Admin role for both source and target servers.

  1. Open the command-line interface that is supported by your operating system.

  2. If necessary, change the current directory to the installation directory for Python. For example (Windows): 

    cd C:\Python 27

  3. Enter the following command: 

    moveIssue src_url src_login src_password trg_url trg_login trg_password src_issueId trg_projectId
    Replace the command-line parameters with values as described here:

    Parameter

    Description

    src_url

    The URL of the source YouTrack server to import issues from.

    src_login

    The username of the account you use to log in to the source YouTrack server.

    src_password

    The password of the account you use to log in to the source YouTrack server.

    trg_url

    The URL of the target YouTrack server to import issues to.

    trg_login

    The username of the account you use to log into the target YouTrack server.

    trg_password

    The password of the account you use to log in to the source YouTrack server.

    src_issueId

    The issueID for the issue that you want to import to the target YouTrack instance.

    trg_projectId

    The projectID of the project in the target YouTrack instance that you want to import the source issue to.

  4. Check the target YouTrack server and verify that the issue was imported correctly.

Troubleshooting

If you encounter any errors when you run the import script, see if any of the following conditions apply.

Condition

Error for [/user/login]: 302: Moved Temporarily

Cause

The value that you used for the target_url parameter is incorrect. The most common mistake is to enter the base URL for a YouTrack instance without /youtrack at the end of the URL.

Solution

Change the value of the target_url parameter and run the import the script again. Use the value that is shown as the Base URL setting for your YouTrack service.

  1. For YouTrack Standalone, copy the value from the Base URL setting on the Global Settings page.

  2. For YouTrack InCloud, copy the value from the Base URL setting on the Domain Settings page.

Condition

Error for [<resource>]: 403: Forbidden: You have no permissions for <resource>

Cause

The user account that you used to run the import script does not have permission to read or update the target resource. The resource URL indicates which entity is not accessible to the user.

Solution

Run the import script with a user account that has sufficient permissions to update the target resource.