YouTrack InCloud 2017.4 Help

Import from Redmine

Follow the instructions on this page to import issues from Redmine 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 Redmine database and the issue attributes in YouTrack.
  3. Import your issues.

Import Details

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

EntityDescription
ProjectsThe Python script lets you import all issues from a source project at once. If the project does not already exist, a new project is created.
  • The project name and ID are assigned based on the values from the Redmine database.
  • The user who executes the import script is set as the project lead.
UsersSeveral issue attributes like reporterName and Assignee store references to user accounts. User accounts in Redmine can use an email address for login, so the import script checks accounts for login first, then an email address. For each account that does not match the login or email for an existing user in YouTrack, a new user account is created.

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.

GroupsRedmine user accounts can be assigned to groups. For imports from Redmine versions 2.1 and later, these groups are imported to YouTrack. Groups names and memberships are taken from the source database.
RolesIn Redmine, role assignments define the permissions that members have in a project. For imports from Redmine versions 2.2 and later, these roles can be imported to YouTrack. Role names and assignments are taken from the source database. The permissions are mapped to the permission scheme in YouTrack according to the definitions in your mapping file.
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.
Work ItemsWhen you import data from the time tracking module in Redmine, the values that are stored as Spent time are converted to time spent in work items. The value that is used for the Spent Time field in YouTrack is derived from the time spent that is added to imported work items.

The Redmine REST API does not support watchers and tags. These entities are not imported to YouTrack.

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

The import script requires REST API support in Redmine.

To enable REST API support:

  1. In your Redmine instance, open the Administration > Settings > Authentication tab.
  2. Select the Enable REST web service checkbox.

Customize the Mapping Definitions

The next step is to map the fields in your Redmine database to attributes in YouTrack. The client library contains a sample file that you can customize to match your import data. The file is saved as mapping.py in the python/redmine 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 mapping.py 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 Redmine database is mapped to the desired values in YouTrack. For a description of the default mappings, see Default Mapping.
  3. 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/redmine directory.
    • Open the __init__.py file in the python/redmine subfolder of the client library.
    • Locate the reference to the mapping module and set the value to the name of your mapping file (without the .py extension). Use the following example as a guide:
      from client import RedmineClient from client import RedmineException from <mapping file name> import Mapping
    • Save and close the __init__.py file.
    If you modified the default mapping.py file instead, save and close the file.

Import Your Data

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

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. Run the import script. The script supports two authentication options for Redmine. You can use either an API key or a login/password pair. The script supports the following command-line arguments:
    ArgumentDescription
    -aRuns the import script using an API key for authentication. Requires a value for the api_key parameter.
    -tEnables import from the time tracking module in Redmine.
    -hDisplays a short help file for the import script.
    • To authenticate with an API key, run the import script with the -a option:
      python redmine2youtrack.py -a api_key r_url y_url y_user y_password [project_id ...]
      Replace the command-line parameters with values as described here:
      ParameterDescription
      api_keyThe Redmine API key. You can find the Redmine API key on your user account page.
      r_urlThe URL of your Redmine instance.
      y_urlThe 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
      y_userThe login for a YouTrack administrator account.
      y_passwordThe password for the YouTrack administrator account.
      project_idThe ID of the Redmine project that you want to import.
    • To run the import script with a login/password pair, enter the following command:
      python redmine2youtrack.py r_url r_user r_pass y_url y_user y_password [project_id ...]
      Replace the command-line parameters with values as described here:
      ParameterDescription
      r_urlThe URL of your Redmine instance.
      r_userThe username to log in to Redmine.
      r_passThe password for the account used to log in to Redmine.
      y_urlThe 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
      y_userThe login for a YouTrack administrator account.
      y_passwordThe password for the YouTrack administrator account.
      project_idThe ID of the Redmine project that you want to import.
    • 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 Redmine to YouTrack. The file is saved as mapping.py in the python/redmine subfolder of the client library.

The import script __init__.py 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.

Custom Fields

The FIELD_NAMES dictionary maps field names in Redmine to custom fields in YouTrack. You can update the mappings in this section to import data to specific custom fields. The default mapping file contains definitions for the following fields:

FIELD_NAMES = { 'id' : 'numberInProject', 'subject' : 'summary', 'author' : 'reporterName', 'status' : 'State', 'priority' : 'Priority', 'created_on' : 'created', 'updated_on' : 'updated', 'tracker' : 'Type', 'assigned_to' : 'Assignee', 'due_date' : 'Due Date', 'estimated_hours' : 'Estimation', 'category' : 'Subsystem', 'fixed_version' : 'Fix versions', 'redmine_id' : 'Redmine ID' }

Pay attention to the following guidelines when you edit the custom field mapping:

  • The left side of the mapping references the field name in Redmine. These values correspond to the field references in the Redmine database.
  • The right side of the mapping references an issue attribute in YouTrack. Base attributes use the attribute names that are specified in the Import REST API. For mappings to custom fields, use the custom field name.
  • If you do not specify a mapping for a field in Redmine that does not match a target field in YouTrack, a custom field is created with the same name as in Redmine.

Custom Field Types

The FIELD_TYPES dictionary maps data types in Redmine to custom field types in YouTrack. If you have added fields to the mapping for custom fields, add a corresponding entry to this dictionary to define how the data is stored in YouTrack. The default mapping file contains definitions for the following field types:

FIELD_TYPES = { 'Type' : 'enum[1]', 'State' : 'state[1]', 'Priority' : 'enum[1]', 'Assignee' : 'user[1]', 'Due Date' : 'date', 'Estimation' : 'period', 'Subsystem' : 'ownedField[1]', 'Fix versions' : 'version[*]', 'Redmine ID' : 'integer' }

Pay attention to the following guidelines when you edit the field type mapping:

  • The left side of the mapping references the name of the custom field in YouTrack. These values must exactly match the custom field name in the FIELD_NAMES dictionary.
  • The right side of the mapping references the field type in YouTrack. For a list of valid types, refer to the Administration REST API.
  • If the target field already exists in YouTrack, you do not need to include it here.
  • You cannot change the data type of an existing field. For example, if the existing Assignee field stores single values (user[1]), you cannot use user[*] in the mapping file and import multiple assignees. You must first update this property for the Assignee field in the YouTrack user interface, then import the data.

Values for Custom Fields

The CONVERSION dictionary maps enumerated values for Redmine fields to value for custom fields YouTrack. The default mapping file contains mappings for issue State and Priority.

CONVERSION = { 'State': { 'Resolved' : 'Fixed', 'Closed' : 'Fixed', 'Rejected' : "Won't fix" }, 'Priority': { 'High' : 'Major', 'Low' : 'Minor', 'Urgent' : 'Critical', 'Immediate' : 'Show-stopper' } }

Permissions

The PERMISSIONS dictionary maps permissions from Redmine to permissions in YouTrack. Redmine permissions that do not have a corresponding permission in YouTrack are commented out.

The default mapping includes definitions for the following permissions in YouTrack:

PERMISSIONS = { 'add_project' : 'CREATE_PROJECT', 'edit_project' : 'UPDATE_PROJECT', 'close_project' : 'DELETE_PROJECT', 'manage_members' : [ 'CREATE_USER', 'READ_USER', 'UPDATE_USER', 'CREATE_USERGROUP', 'READ_USERGROUP', 'UPDATE_USERGROUP' ], 'add_messages' : 'CREATE_COMMENT', 'edit_messages' : 'UPDATE_NOT_OWN_COMMENT', 'edit_own_messages' : 'UPDATE_COMMENT', 'delete_messages' : 'DELETE_NOT_OWN_COMMENT', 'delete_own_messages' : 'DELETE_COMMENT', 'view_issues' : 'READ_ISSUE', 'add_issues' : 'CREATE_ISSUE', 'edit_issues' : 'UPDATE_ISSUE', 'delete_issues' : 'DELETE_ISSUE', 'view_issue_watchers' : 'VIEW_WATCHERS', 'add_issue_watchers' : 'UPDATE_WATCHERS', 'delete_issue_watchers' : 'UPDATE_WATCHERS', 'log_time' : 'UPDATE_WORK_ITEM', 'view_time_entries' : 'READ_WORK_ITEM', 'edit_time_entries' : 'UPDATE_WORK_ITEM', 'edit_own_time_entries' : 'UPDATE_NOT_OWN_WORK_ITEM', }
Last modified: 4 January 2018