You can import issues into YouTrack from a comma-separated values (CSV) file. This option lets you import data from any issue tracker that can export issues in CSV format. Use this option to import issues from Trello (Business Class and Enterprise), Asana, GitHub, GitLab and many others.

• Import Assistant Video Psalm 101
• Import Assistant Video Psalm 119

This procedure requires the following steps:

Files with comma separated values (CSV) are a good and easy way for exchanging data. Also you have the possibility to manipulate the data e.g. Via Microsoft Access, Microsoft Excel or Open Office Calc easily. Photo & Video Import is a simple, no-nonsense photo and video transfer solution to quickly import content from your smartphone, digital camera, camcorder or memory cards onto your PC or tablet. The program keeps track of previously imported files and optionally let you pick the import destination and how to store the imported content (in date.

1. Set up your local environment.

2. Prepare your import files.

3. Map the fields in your CSV file to issue attributes in YouTrack.

4. Import your issues.

Import Details

If the import file 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:

Set Up Your Environment

Import to YouTrack is supported with 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:

1. Download and install Python. The import scripts are 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. Open the command-line interface that is supported by your operating system.

3. Verify that your Python installation includes the virtualenv package by running the following command:

   This ensures that you are able to execute commands in YouTrack import scripts without encountering a Command not found message.

4. Install the package that contains the import scripts with 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:

Prepare Your Import Files

One of the most important steps in this procedure is to know exactly what you are going to import into YouTrack. You should inspect your import files and verify that the data is formatted properly. The following sample shows sample data that can be imported into YouTrack.

To ensure that your import is successful, follow these steps:

1. Open your CSV file in a spreadsheet editor. It's much easier to read and, if necessary, modify the data when it is presented in discrete columns and rows.

2. Check the first row (record) in the file. This record should be a header that contains a list of field names.

3. Check your header for required fields. Your header must include fields that can be mapped to each of the following issue attributes: project_id, project_name, numberInProject, reporterName, created, and summary. If these columns are not present, add them to your CSV file.

4. Important! Check that the field that is mapped to the numberInProject issue attribute does not contain an alphanumeric prefix. If it does, please change the prefix to be letters-only, and then export this project to the CSV file one more time.

   YouTrack assumes that the field that is mapped to the numberInProject is an integer number. However, sometimes, this exported issue number can also contain a prefix - a short name of the project or a projectID, and so on. Let's say, the issue numbers are exported as {project_short_name}-{number_in_the_project} (for example, DX-12345). In this case, for the import to work, this {project_short_name} must not contain any digit. In other words, you must check that the value for the numberInProject does not look like DX1-12345 or D1X-12345.

You might also consider whether it's safe to import your data into an existing project. If you're not entirely sure about the contents of your CSV file, you can update the values in the Project ID and Project columns to import your data into a new, empty project instead.

Importing Issue Links

The csv2youtrack import script supports importing issue links. To import links between issues from your CSV file, follow these guidelines:

• Add a column to your CSV file with the name 'Links'.

• Do not add 'Links' field to your Mapping file.

• Specify links between issues with the following pattern:
  '{Link type}{csv_field_delimiter}{issue ID to which to link the current}{csv_value_delimiter}{Link type}{csv_field_delimiter}{issue ID to which to link the current}...'
  For the {Link type}, enter the type as shown on the Issue Link Types page in the administration section of YouTrack.

  Use the following example as a guide.

  mapping.json

  'csv_field_delimiter': ',','csv_value_delimiter': ';',

  data.csv

  'Issue Id','Project ID','Project','Summary','Reporter','Created','Links'SP-2019','SP','Scrum Project','two scrum','Anastasia Bartasheva','2017-10-2021:00:00','Relates,SP-2020;Depend,SP-2021'

• The script only imports links that use existing link types. Links that use unknown types are not imported.

• For the issue to be linked, you can either use the issue number in the project or the full issue ID. If you specify the number only, the project ID for the current issue is used to create the issue ID for the target issue.

Importing Comments

You also want to verify how your source application exports comments. Many applications export comments as fields that do not have a field name in the header. This format is illustrated in the following example:

Comments in this format are imported without any related attributes. These attributes are generated during import.

• Comments are added on behalf of the guest user account.

• The comment date is set to the current date and time.

The client library lets you import comments that are stored in separate CSV files. If you have the possibility to extract this data and format it correctly, you can import comments with attributes and issue attachments.

For comments, the CSV file must contain the following fields in the specified order:

For the field names in the header, you can specify any value you want, but the field name for the comment text should be empty. The most important requirement is that you present these fields in the specified order. For each comment, the project ID and issue number must correspond to a record in the CSV file that contains your issue data.

Use the following example as a guide.

Importing Attachments

You also have the ability to import issue attachments from a separate CSV file.

For attachments, the CSV file uses the following format:

For the field names in the header, you can specify any value you want, but the field name for the path to the attachment files should be empty. The most important requirement is that you present these fields in the specified order. For each attachment, the project ID and issue number must correspond to a record in the CSV file that contains your issue data.

Use the following example as a guide.

Build Your Mapping File

The next step is to map the fields in your source file to issue attributes in YouTrack. You can use the csv2youtrack script to generate a sample mapping from your source CSV file.

To generate a mapping file:

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):

3. Enter the following command:

   csv2youtrack -g -m mapping.json source.csv

   • 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 and assigned the same name as the CSV file with the .json extension. 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.

   • The source.csv parameter specifies the location of the source CSV file. Replace this value with the full path and filename of your source CSV file. Don't forget to include the .csv extension.

   • If the command is executed successfully, a message with the location of the generated file is printed in the command-line interface.

4. Open the generated mapping file and map the fields from your source file to their corresponding issue attributes in YouTrack. If your source file contains one or more fields that you don't want to import, you can remove the references from the mapping file. Use the example that follows as a guide.

The following mapping file was generated from the sample CSV file shown in the previous procedure. To improve readability, we have aligned the right side of the mappings in the sample. You don't need to align the columns in your mapping file and can leave them as they were generated.

Your job is to match up the fields from your CSV file to the corresponding attributes in YouTrack. When done, you should end up with mappings for all of the fields in your source file that you want to import. If your source file does not contain values for optional fields, you can delete these mappings.

To customize the generated mapping file:

1. For the csv_field_delimiter, enter the character that delimits fields in your CSV file. If the delimiter in your CSV file and the character that is specified for this parameter are not the same, the import fails.

2. For the csv_value_delimiter, enter the character that separates multiple values for fields in your CSV file.

3. For the date_format_string, specify the format that is used for date fields in your CSV file. This parameter accepts directives that are used by the strftime(format) method in the Python Standard Library. You can find a complete list of directives in the Python documentation.

   • In our sample mapping file, the %Y-%m-%d %H:%M:%S pattern recognizes date values in the format 2015-10-20 21:00:00.

   • The default value uses the pattern %A, %B %d, %Y %I:%M:%S %p %z, which recognizes date values in the format Tuesday, October 20, 2015 09:00:00 PM +0300.

   Just look at the format that is used in your CSV file and replace each value with the corresponding directive. Enter punctuation marks and whitespace between directives as they appear in your fields.

4. In the field_names section of the file, map the fields from your source file to their corresponding issue attributes in YouTrack. If your source file contains a field that you don't want to import, you can remove the reference from the mapping file. Pay attention to the following guidelines when you map your fields:

   • The first set of fields in this section are common issue attributes in YouTrack.

   • The second set of fields correspond with the columns from your CSV file. The fields are sorted in alphabetical order.

   • The mapping file must contain mappings for all of the following issue attributes: project_id, project_name, numberInProject, summary, created, and reporterName. These fields are listed at the top of this section. If any of these fields are not included in the mapping, the import fails with an error.

   • The left side of the mapping references the field name in your CSV file. These values must be specified exactly as written in the header.

   • 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 the column names in the source file match the default names for target custom fields in YouTrack, you don't need to map them explicitly. This includes default fields like Type, Priority, and State. You should, however, verify that the data that is stored in the source file matches the data type for the target field.

   • Each field in your source file can only be mapped to a single target field. For example, you cannot map the issue summary to both the issue summary and description.

5. In the field_types section of the file, specify the data type for fields that are created during import. Consider the following guidelines:

   • 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.

6. Save your changes and close the mapping file.

Here's what our sample mapping file would look like following this procedure. Again, we have aligned the right side of the mappings to improve the readability of the sample.

As you see from this example, we can skip mappings for default custom fields like Type, Priority, and State. The column names in the source CSV file match the names for the corresponding fields in YouTrack. The field types are already defined as well.

We include mappings for other default custom fields like Assignee and Subsystem so we can specify that the fields store single values.

Import Your Data

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

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):

3. Enter the following command:

   csv2youtrack -m mapping.json -t token -u login -p password -c comments_file -a attachments_file source_file target_url

   The source_file and target_url must be the last arguments that are specified in the script. Replace the command-line parameters with values as described here:

   Parameter	Description
   mapping.json	Required. Use with the -m option to specify the full path and filename of your mapping file.
   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, seeCreate 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.
   comments_file	Optional. Use with the -c option to specify the full path to a CSV file that contains issue comments.
   attachments_file	Optional. Use with the -a option to specify the full path to a CSV file that contains references to attachments.
   source_file	The full path to the source CSV file. Include the filename and extension.
   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

   • The command executes the Python import script.

   • If successful, the following line is printed in the command-line interface for each issue:

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 source file and/or mapping file.

   • Run the import script again.

Troubleshooting

If you encounter any errors when you run the import script, see if any of the following conditions apply.

Import Assistant Video Psalm 101

Import Assistant Video Psalm 119