Import Issues from Another YouTrack Server
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:
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. 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:
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.
-
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:
Open the command-line interface that is supported by your operating system.
If necessary, change the current directory to the installation directory for Python. For example (Windows):
cd C:\Python27
-
Enter the following command:
youtrack2youtrack [OPTIONS] AUTH_OPTIONS source_url target_url [projectId ...]
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
-
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:
Open the command-line interface that is supported by your operating system.
If necessary, change the current directory to the installation directory for Python. For example (Windows):
cd C:\Python 27-
Enter the following command:
moveIssue src_url src_login src_password trg_url trg_login trg_password src_issueId trg_projectIdReplace 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. 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 |
Solution | Change the value of the
|
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. |