Import from Bugzilla - Help | YouTrack Standalone

Import Details

If the Bugzilla database contains references to entities that do not already exist in YouTrack, they are created. The user account that you use to run the import should have permission to create projects, issues, users, and possibly more. We recommend that you use an account with a System Admin role to execute the import script.

New entities are created as follows:

Entity	Description
Projects	If the project that is referenced in the import source does not already exist, a new project is created. The project name and ID are assigned based on the values from the Bugzilla database. The user who executes the import script is set as the project owner.
Users	Several issue attributes like `reporterName` and `Assignee` store references to user accounts. The values in the import are checked against existing user accounts by email. For each new value that does not match the email for an existing user, a new user account is created. The email address is also used as the login for the imported user account. All new user accounts are assigned randomly-generated passwords. To log in to YouTrack, imported users must click the Reset password link on the login page and create a new password. 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.
Custom Fields	If the import data contains a field that does not exist in YouTrack, the custom field is created and added to the target project. The field name and type are set according to the definitions in your mapping file. The properties for the custom field are set as follows: `autoAttached=true`, `isPrivate=false`, `defaultVisibility=false`.
Field Values	If the source file contains new values for an existing field, they are added to the current set of values.

Set Up Your Environment

Import to YouTrack is supported by 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 import scripts are 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 a Python library for the MySQL database. For example, MySQLdb.
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

Customize the Mapping Definitions

The next step is to map the fields in your Bugzilla database to issue attributes in YouTrack. You can use the bugzilla2youtrack script to generate a sample mapping file.

You only need to customize the mapping file if you have customized the issue attributes in Bugzilla. To use the default mapping definitions, skip this procedure and import your data.

To generate a mapping file:

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:
bugzilla2youtrack -g -m mapping.json
- The -g option tells the script to generate the mapping file.
- The -m option overrides the default path and filename for the mapping file. If you don't pass this option, the file is generated in the current directory as mapping.json. If you want to specify another location and/or filename, specify a value for the parameter with the full path of the target directory and/or desired name.
- If the command is executed successfully, a message with the location of the generated file is printed in the command-line interface.

To customize the mapping definitions:

Open the generated mapping file.
Update the mapping to ensure that all of the data that you want to import from the Bugzilla database is mapped to the desired values in YouTrack. If the file contains one or more fields that you don't want to import, you can remove the references from the mapping file. For a description of the default mappings, see Default Mapping.
Check that the value for the bz_db_charset parameter matches the character encoding for your Bugzilla database. Bugzilla versions 2.22 and later use UTF-8 character encoding.
Save your changes and close the mapping file.

Import Your Data

The last step is to run the command that imports your data from Bugzilla.

To import your data:

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:

bugzilla2youtrack -m mapping.json -t token -u login -p password target_url bz_db bz_host bz_port bz_login bz_pass [bz_product]

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

Parameter	Description
`mapping.json`	Use with the `-m` option to specify the full path and filename of your custom mapping file. If you don't pass this option, the default mapping file is used instead.
`token`	When used with the `-t` option, a permanent token that is used to authenticate your administrator account in YouTrack. This is the preferred method of authentication. If you use this option, skip the `-u` and `-p` options. To learn how to generate a permanent token, see Create a Permanent Token. Alternatively, you can use the `-T` option and specify the full path and filename for a file that contains a permanent token.
`login`	When used with the `-u` option, the login for a YouTrack administrator account. You must also specify a value for the `-p` option.
`password`	When used with the `-p` option, the password for the YouTrack administrator account.
`target_url`	The base URL of the target YouTrack server. For YouTrack InCloud instances, your base URL includes the trailing `/youtrack`. For example: `https://company.myjetbrains.com/youtrack`
`bz_db`	The name of the source database to import from Bugzilla. The default database name is `bugs`.
`bz_host`	The URL of the Bugzilla source database.
`bz_port`	The port to access the Bugzilla source database. If not configured specifically, the default port number is 3306.
`bz_login`	The username to log in to the Bugzilla source database.
`bz_pass`	The password for the account used to log in to the Bugzilla source database.
`bz_product`	The optional name of the source product to import from Bugzilla. To import multiple products, separate product names with commas. If empty, all products in the database are imported.

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 project or projects that you imported issues into and verify that the data is presented properly. If you are not satisfied with the results and want to re-import the data:
- Delete all of the issues that were created during import. If you imported issues into a new project, simply delete the project.
- Edit your mapping file.
- Run the import script again.

Default Mapping

The repository includes a default mapping file for importing bugs from Bugzilla to YouTrack. The file is saved as defaultBzMapping.py in the youtrackutils/bugzilla subfolder.

The import script references the default mapping file. If you create a custom mapping file, use the -m option in your import script and specify the full path and filename of your file as described in the previous section.

Status and Resolution

Values for bug Status in Bugzilla are mapped to values for the State field in YouTrack. The Resolution in Bugzilla is mapped to values for the State field that are marked with the Resolved property.

These mappings are specified in the state_map section of the file. Here, we have aligned the right side of the mappings to improve the readability of the sample.

The left side of the mapping corresponds to the name of the Status and Resolution values in Bugzilla.
The right side of the mapping shows the target values for the State field in YouTrack.

state_map = {
    "UNCONFIRMED"   : "Open",
    "CONFIRMED"     : "Submitted",
    "NEW"           : "Submitted",
    "ASSIGNED"      : "Submitted",
    "REOPENED"      : "Reopened",
    "FIXED"         : "Fixed",
    "INVALID"       : "Won't fix",
    "WONTFIX"       : "Won't fix",
    "MOVED"         : "Won't fix",
    "LATER"         : "Won't fix",
    "IN_PROGRESS"   : "In Progress",
    "DUPLICATE"     : "Duplicate",
    "VERIFIED"      : "Verified",
    "RESOLVED"      : {"FIXED": "Fixed", "*": "Won\'t fix", "DUPLICATE": "Duplicate"}
}

Custom Field Types

The definitions for field types in Bugzilla are mapped to specific field types in YouTrack. These mappings are specified in the cf_types section of the file.

The left side of the mapping corresponds to the numeric value for the field type in Bugzilla.
The right side of the mapping shows the target field type in YouTrack.
The values that follow the # sign represent the field type IDs in the Bugzilla database.

cf_types = {
    "1": "string",   # FIELD_TYPE_FREETEXT
    "2": "enum[1]",  # FIELD_TYPE_SINGLE_SELECT
    "3": "enum[*]",  # FIELD_TYPE_MULTY_SELECT
    "4": "string",   # FIELD_TYPE_TEXTAREA
    "5": "date",     # FIELD_TYPE_DATETIME
    "7": "string"    # FIELD_TYPE_BUG_URLS
}

The FIELD_TYPE_BUGID (numeric id "6") field type in Bugzilla is imported to YouTrack an issue link. If you prefer a different mapping, define it manually in your mapping file.