YouTrack Standalone 2017.4 Help

Import from Mantis Bug Tracker

Follow the instructions on this page to import issues from the Mantis Bug Tracker (MantisBT) using a dedicated module from the YouTrack Python Client Library. This procedure requires the following steps:

  1. Set up your local environment.
  2. Customize the mapping between the fields in your MantisBT database and the issue attributes in YouTrack.
  3. Import your issues.

Import Details

If the MantisBT 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:

ProjectsIf 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 MantisBT database.
  • The user who executes the import script is set as the project lead.
  • Parent projects and their sub-projects are imported into a single project. The mapping file includes a parameter that lets you reference the parent project in issues that belong to a sub-project.
UsersSeveral issue attributes like reporterName and Assignee store references to user accounts. The values in the import are checked against existing user accounts by Login. For each new value that does not match the login for an existing user, a new user account is created.
  • YouTrack does not support whitespace characters in logins. Whitespace characters in the mantis_user.user_name are replaced with underscores.
  • 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 FieldsIf 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 ValuesIf 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 the YouTrack Python Client Library. This library is basically a wrapper for the YouTrack REST API. You won't actually need to do any programming in Python, but you do need to install Python and download the client library.

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 a Python library for the MySQL database. For example, MySQLdb.
  3. Download the latest version of the YouTrack Python Client Library from GitHub.
  4. Extract the contents of the ZIP archive to a folder in your local directory. You can extract the files to whichever folder you prefer.

Customize the Mapping Definitions

The next step is to map the fields in your MantisBT database to issue attributes in YouTrack. The client library contains a sample file that you can customize to match your import data. The file is saved as in the python/mantis subfolder of the client library. This file contains mappings for all of the fields that are required for successful import and definitions for most custom field types.

To use the default mapping definitions, skip this procedure and import your data.

To customize the mapping definitions:

  1. Either open the file or open a new file in a text editor and paste the content of the default mapping file.
  2. Verify that all of the data in your MantisBT database is mapped to the desired values in YouTrack. For a description of the default mappings, see Default Mapping.
  3. Check that the value for the mantis.CHARSET parameter matches the character encoding for your MantisBT database. MantisBT versions 1.1.0x and later use UTF-8 character encoding.
  4. To determine how sub-projects are handled during import, set the value for the mantis.BATCH_SUBPROJECTS parameter.
    • If True, a Subproject custom field is added to the target project in YouTrack. The sub-project name is set as the value for this field in issues that belong to sub-projects. For issues in the parent project, the value is set to Undefined.
    • If False, relationships between parent and sub-projects are ignored.
  5. If you created a new file, perform the following steps:
    • Save your mapping file with the extension .py and add it to the <unzipped library directory>/python/mantis directory.
    • Open the file in the python subfolder of the client library.
    • Locate the reference to the mantis module and set the value to the name of your mapping file (without the .py extension). Use the following example as a guide:
      import urllib2 from youtrack.connection import Connection from mantis.mantisClient import MantisClient from youtrack import * import sys import mantis import mantis.<mapping file name> from StringIO import StringIO from youtrack.importHelper import * import youtrack.importHelper
    • Save and close the file.
    If you modified the file instead, save and close the file.

Import Your Data

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

To import your data:

  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:
    python target_url target_login target_pass mantis_db_name mantis_db_host mantis_db_port mantis_db_login mantis_db_pass mantis_project mantis_project mantis_project
    Replace the command-line parameters with values as described here:
    Parameter Description
    target_urlThe base URL of the target YouTrack server. For YouTrack InCloud instances, your base URL includes the trailing /youtrack. For example:
    target_loginThe login for a YouTrack administrator account.
    target_pass The password for the YouTrack administrator account.
    mantis_db The name of the source database for the MantisBT import.
    mantis_host The URL of the MantisBT source database.
    mantis_port The port to access the MantisBT source database. If not configured specifically, the default port number is 3306.
    mantis_login The username to log in to the MantisBT source database.
    mantis_pass The password for the account used to log in to the MantisBT source database.
    mantis_project The name of the source project to import from MantisBT. To import multiple projects, separate project names with commas.
    • 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 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 Python Client Library includes a default mapping file for importing issues from MantisBT to YouTrack. The file is saved as in the python/mantis subfolder of the client library.

The import script contains a reference to the default mapping file. If you create a custom mapping file with a different name, update the reference to the mapping file in the script as described in the above procedure.

Resolution and Status

Values for issue Resolution and Status in MantisBT are mapped to values for the State field in YouTrack.

MantisBT RESOLUTION YouTrack State
10 (open) "Open"
20 (fixed) "Fixed"
30 (reopened) "Reopened"
40 (unable to reproduce) "Can't Reproduce"
50 (not fixable) "Won't fix"
60 (duplicate) "Duplicate"
70 (no change required) "Obsolete"
80 (suspended) "Incomplete"
90 (won't fix) "Won't fix"
MantisBT STATUS YouTrack State
40 (confirmed) "Verified"


Values for issue Priority in MantisBT are mapped to values for the Priority field in YouTrack.

MantisBT PRIORITY YouTrack Priority
10 (none) "0" (Minor)
20 (low) "0" (Minor)
30 (normal) "1" (Normal)
40 (high) "2" (Major)
50 (urgent) "3" (Critical)
60 (immediate) "4" (Show-stopper)

Links between issues in MantisBT are mapped to specific issue link types in YouTrack.

MantisBT LINK_TYPES YouTrack Issue Link Type
0 (duplicate of) "Duplicate"
1 (related to) "Relates"
2 (parent of) "Depend"

Reproducibility and Severity

Issue REPRODUCIBILITY and SEVERITY are imported to YouTrack as new custom fields. These fields use the same names and store multiple enumerated values (enum[*] type).

MantisBT REPRODUCIBILITY Reproducibility in YouTrack
10 "Always"
30 "Sometimes"
50 "Random"
70 "Have not tried"
90 "Unable to reproduce"
100 "N/A"
MantisBT SEVERITY Severity in YouTrack
10 "Feature"
20 "Trivial"
30 "Text"
40 "Tweak"
50 "Minor"
60 "Major"
70 "Crash"
80 "Block"

Custom Field Types

The definitions for field types in MantisBT are mapped to specific field types in YouTrack.

MantisBT CF_TYPE (numeric) MantisBT CF_TYPE YouTrack Field Type
0 String "string"
1 Numeric "integer"
2 Float "string"
3 Enumeration "enum[1]"
4 Email "string"
5 Checkbox "enum[1]"
6 List "enum[1]"
7 Multiselection list "enum[*]"
8 Date "date"
9 Radio "enum[1]"

Custom Fields

You can specify additional mappings between issue fields in MantisBT and YouTrack. To define additional mappings, add definitions to the FIELD_NAMES dictionary. The default mapping file contains definitions for the following custom fields:

mantis.FIELD_NAMES = { u"severity" : [u"Severity", u"Type"], u"handler" : [u"Assignee"], u"status" : [u"State"], u"resolution" : [u"State"], u"category" : [u"Subsystem"], u"version" : [u"Affected versions"], u"fixed_in_version" : [u"Fix versions"], # DO NOT remove Fix versions form this list, if needed you can add one more field # but DO NOT delete Fix versions u"build" : [u"Fixed in build"], u"os_build" : [u"OS version"], u"subproject" : [u"Subproject"], u"os" : [u"OS"], u"due_date" : [u"Due date"], u"target_version" : [u"Target version"] # it's better to import this fields with version type }

Field Types for Specific Fields

You can also modify the target field types (field types in YouTrack) using the FIELD_TYPES dictionary. For default custom fields in YouTrack, use the default field type definitions.

The following dictionary is defined in the default mapping file:

mantis.FIELD_TYPES = { u"Priority" : "enum[1]", u"Type" : "enum[1]", u"State" : "state[1]", u"Fix versions" : "version[*]", u"Affected versions" : "version[*]", u"Assignee" : "user[1]", u"Fixed in build" : "build[1]", u"Subsystem" : "ownedField[1]", u"Subproject" : "ownedField[1]", u"Severity" : "enum[1]", u"Platform" : "string", u"OS" : "string", u"OS version" : "string", u"Reproducibility" : "enum[1]", u"Due date" : "date", u"Target version" : "version[1]" }
Last modified: 4 January 2018