Redmine Importer Documentation¶

In general, the Redmine Importer will take the columns of a .csv file and map them to the fields of issues, and create one issue for each line of the the .csv file. It’s a good way to create Redmine issues when you have a large volume of issues to manage.

Below is a description of how to use the Importer. Also, see the SampleFiles page for a list of sample CSV files you can upload.

Basic Usage¶

Select the “Import” item on the project bar and you will see the first CSV file upload screen. At this screen, you should click the “Choose File” button to select the CSV file to be uploaded. (For existing projects, in the project Settings, inside Modules, you will have to enable “Importer” for the Import item to appear.)

In the example below, the user has already selected “CustomField.csv” and is about to click the “Upload File” button.

Once you click “Upload File”, the Column Matching screen will be displayed. At this second screen, the most important thing is to confirm the mapping from your column headers to the available fields of a Redmine issue. If you are importing relationships between issues, you will also want to see the section on “Unique-valued Column” below to verify your other settings. When the options are correct, hit the “Submit” button.

Your issues will be imported and a summary of the number of records inserted and any problems found will be displayed. Note that importing a large number of issues can take a long time. If you left the “Send notification emails” checked, emails will be sent according to normal Redmine settings; if you turned that checkbox off, no emails will be sent (this can be handy when doing something like porting issues from one installation to another).

CSV Format Notes¶

You should always provide a header row in your CSV file. The titles in this header row will help Redmine Importer figure out which column in your CSV files corresponds to which field of the Redmine issue.

It is suggested to always use UTF-8 encoding, comma as separator, and double-quote as delimiter for your CSV file. However, if you are working with CSV files from a legacy source, you can tweak the CSV file format details via the options in the CSV Upload screen.

The maximum supported size of CSV file depends on your database backend; it’s 4 megabytes for MySQL.

Standard Fields¶

Here is the list of headers the Redmine will automatically recognize; they correspond to fields of a Redmine issue.
Note that while they are all listed here for completeness, all fields are optional. You only need to provide data for the items you actually want to set.

• Subject: The main subject line for the issue. Remember not to use multiple lines here.
• Description: The main description. This value can be multiple lines.
• Assigned To: The username of the person the ticket should be assigned to. This must exactly match the login as found in the Redmine user account.
• Fixed version: The target version field. Existing target versions can be entered here. If the “Auto-add target versions” checkbox is on, any new target versions will be automatically added to the project; if the checkbox is off, unknown target versions will be silently skipped.
• Author: The author of the ticket. It’s rarely necessary to supply this, because it will default to the user who does the upload.
• Category: The ticket category. Existing categories can be entered here. If the “Auto-add categories” checkbox is on, any new categories will be automatically added to the project; if the checkbox is off, unknown categories will be silently skipped.
• Priority: Ticket priority field.
• Tracker: Which Tracker within this project the ticket should be entered in. Normally it’s not needed to provide this, since the default Tracker can be set on the upload page.
• Status: The issue status. Redmine Importer will not create new issue statues, you need to configure those ahead of time in the Settings tab.
• Start date: The start date for the issue, expressed as a string. A number of different date formats will work, but the format (common in America) of a two-digit year (e.g., 03/06/03) is not supported. Be sure to use a format with a four-digit year. Most testing has been done with ISO-8601, which is YYYY-MM-DD.
• Due date: The due date for the issue. Same note as above about date formats applies.
• Done Ratio: Percentage done for the issue, as an integer between 0-100.
• Estimated hours: Estimated time expressed in man-hours.
• Watchers: This column is a comma-separated list of the login names of watchers to add to the new ticket.
• Task Relations: You can provide a column header using any of the values below to set relationships to other tasks. If you import relationships, you must set a unique-valued column. Also see the "Issue Relationships Restriction" section below.
  • blocked by
  • blocks
  • duplicated by
  • duplicates
  • follows
  • precedes
  • related to

• Parent Issue: This allows you to set the parent task of the task being imported. If you provide values for this column, you must set a unique-valued column; see below.
• Id: The Redmine issue number. This would only be used when doing issue updates, see Advanced Usage below.

If you use the column headers given above, they should automatically match no matter what language Redmine is displaying.
In addition to the strings above, Redmine Importer will try to automatically match columns which are the same as the localized version of the field names in Redmine. If the columns don’t match automatically, just be sure to set the field match pulldowns in the Column Matching screen.

Custom Fields¶

You should be able to use the importer to import custom fields in the same manner as built-in fields. You need to set the custom fields up in the Settings tab ahead of time; Redmine Importer will not create custom field definitions automatically.

If there is any chance of using your custom field as a unique-valued column (see below) the “Used as a filter” checkbox must be on.

Custom Field Type Notes¶

• The “list” format is not currently supported
• For the “date” format, the acceptable string values depend on the Rails to_date method. I can’t find any documentation of exactly which formats this method accepts, but in particular, it seems to fail on any format with a 2-digit year. Be sure to set your spreadsheet or other program to output four-digit years. YYYY/MM/DD and YYYY-MM-DD formats have been tested to work.
• For “user” fields (Redmine 1.2), the value in the CSV file should be the user’s login name.
• For “version” fields (Redmine 1.2), the value in the CSV file should be name of the target version.

Advanced Usage: Unique-valued Columns and Referring to Other Issues¶

In addition to the basic import functions described above, Redmine Importer supports updating existing issues, setting the parent task of an imported task, and importing task relationships. Doing so requires that one line in your imported CSV file somehow be able to refer to a pre-existing issue or another line in the CSV file.

In these situations, you must specify one column in your CSV file which is a Unique-valued Column, meaning that all the relevant tickets use a different value in this column. This enables you to use the value of that column as a unique identifier when referring to a different issue.

For instance, if you know that all the issues you are working with definitely have different Subject fields, you can use Subject as your Unique-value Column. That means that in your CSV file, when you want to refer to another row, you can refer to it by its subject.
Therefore, you could import parent-child task relationships by having a CSV file like this:

However, it may be difficult to guarantee that issues will always have unique subjects, especially if your users are editing them. Therefore, another way to set up a unique column is to add a custom field in Redmine, and then use the value of the custom field as your Unique Column. If you are using Redmine Importer to transfer information from another system this may be particularly effective; the other system may already have some unique piece of information. Alternatively, if you’re exporting your CSV file from a spreadsheet, it’s quite easy to generate a time+serial number value which is unique for every line.

For instance, if you created a custom field called “External Id” and then wanted to use that as your unique column to import parent/child and dependency relationships, you might end up uploading a CSV file like this:

When creating new issues, it is only required that your unique column be unique among all the issues you are importing. If you want to update existing issues (see below), the unique column must be unique across all issues in the project.

Updating Existing Issues¶

All of the examples so far have talked about using Redmine Importer to create new issues. However, if your Unique Column values are unique across all issues in your project, you can also use Redmine Importer to update existing issues. To enable this, turn on the “Update Existing Issues” checkbox in the Column Matching screen.

In this case, Redmine Importer will use the value in the unique column to query the database and find the existing issue to update. Remember that all of the matching columns from the CSV file will be updated, so you might overwrite values that have changed in Redmine. If you want to skip a column on import, just set it to “Ignore” on the Column Matching screen.

Referring to Other Issues and Ordering in the CSV File¶

Redmine Importer processes your CSV file in order from the beginning to the end. Because of this, when making references to other columns using unique columns, you can only refer to issues that are earlier in the CSV file. You cannot refer to issues that come further down in the file.

If this is unworkable, there’s a straightforward but non-obvious workaround: import the CSV file twice. The first time, set all of the relationship columns to “Ignore” so you’re just importing the basic data. The second time, be sure to set your Unique Column and to turn on the “Update Existing Issues” checkbox. Since all the issues will already exist in the database, they can now be found.

Issue Relationships Restriction¶

Redmine Importer can only have one column mapped to given field value. Because of this, it cannot import more than one issue relationship of the same relationship type in one upload. That is, while in fact Issue C may “follow” both Issue B and Issue A, because you can’t have two columns with the header “follow” you can’t import that information all at once.

The workaround is to import twice, ignoring one of the columns the first time, and turning on “Update Existing Issues” and ignoring the other column the second time.

Updating Existing Issues and Issue Relationships¶

In general, it’s fine to re-import a CSV file that declares issue relationships. Redmine Importer will check whether the relationship already exists and only create any that are missing. However, Redmine Importer cannot delete relationships, so any issue relationships that were created previously will remain in existence even if they are not in the new CSV file.

Updating Existing Issues and Watchers¶

In the same way, if you re-import a file that includes a Watchers column, any new watchers will be added to the issue, but Redmine Importer never deletes existing watchers.

A note about Redmine Issue numbers¶

If you’ve been around databases, you might think that using the Redmine issue number is the obvious solution for Unique Columns. This works fine for updating: if you create a column whose header is “Id”, it will automatically be recognized as the Redmine issue number and used to refer to other tickets. However, this is often inconvenient because the Redmine issue number doesn’t exist until the issue is created – that means it’s impossible to use it to set up in an import. It can also be impractical to get the Redmine issue numbers out of Redmine after the initial creation.

Import Samples¶

In the redmine_importer/test/samples directory, there are some sample .csv files. See SampleFiles for instructions on how to set up and import all of these files, which will give you a good sense of what Redmine Importer can do.