Import from Redmine

Import Details

Entity	Description
Projects	The 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 owner.
Users	Several 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. warning 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.
Groups	Redmine 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.
Roles	In 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 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.
Work Items	When 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.

Set Up Your Environment

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
```

Customize the Mapping Definitions

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

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:
```
redmine2youtrack -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.

Import Your Data

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:

redmine2youtrack -m mapping.json -t token -u login - p password -a api_key r_user r_pass r_url y_url [project_id ...]

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.
`api_key`	When used with the `-a` option, the API key that is used for authentication in Redmine. You can find the Redmine API key on your user account page. If you use the `-a` option to authenticate with an API key, skip the `r_user` and `r_pass` parameters.
`r_user`	The username to log in to Redmine. Specify only when you authenticate in Redmine with a login/password pair.
`r_pass`	The password for the account used to log in to Redmine. Specify only when you authenticate in Redmine with a login/password pair.
`r_url`	The URL of your Redmine instance.
`y_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`
`y_user`	The login for a YouTrack administrator account.
`y_password`	The password for the YouTrack administrator account.
`project_id`	The ID of the Redmine project that you want to import.

The script also supports the following options:

Option	Description
`-t`	Enables import from the time tracking module in Redmine.
`-h`	Displays a short help file for the import script.

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 Redmine to YouTrack. The file is saved as mapping.py in the youtrackutils/redmine 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.

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'
}

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'
}

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.

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',
}

Import from Redmine﻿

Import Details﻿

warning

Set Up Your Environment﻿

To set up your environment:﻿

To enable REST API support:﻿

Customize the Mapping Definitions﻿

To generate a mapping file:﻿

To customize the mapping definitions:﻿

Import Your Data﻿

To import your data:﻿

Default Mapping﻿

Custom Fields﻿

Custom Field Types﻿

Values for Custom Fields﻿

Permissions﻿