Import from Mantis Bug Tracker
Follow the instructions on this page to import issues from the Mantis Bug Tracker (MantisBT) with a Python import script. This procedure requires the following steps:
(Optional) Customize the mapping between the fields in your MantisBT database and the issue attributes in YouTrack.
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:
Entity | Description |
---|---|
Projects | If the project that is referenced in the import source does not already exist, a new project is created.
|
Users | Several issue attributes like
|
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.
|
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 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 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 MantisBT database to issue attributes in YouTrack. You can use the mantis2youtrack
script to generate a sample mapping file.
You only need to customize the mapping file if you have customized the issue attributes in MantisBT. 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:
mantis2youtrack -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 asmapping.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 MantisBT 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
charset
parameter matches the character encoding for your MantisBT database. MantisBT versions 1.1.0x and later use UTF-8 character encoding.To determine how sub-projects are handled during import, set the value for the
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.
Save your changes and close the mapping file.
Import Your Data
The last step is to run the command that imports your data from MantisBT.
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:
mantis2youtrack -m mapping.json -t token -u login -p password target_url 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
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
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
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 defaultMantis.py
in the youtrackutils/mantis
subfolder of the repository.
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.
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" |
Priority
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) |
Issue Link Types
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 | "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 defaultMantis.py
mapping file contains definitions for the following custom fields:
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:
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]"
}