Import from Google Sheets

The import from Google Sheets lets you migrate data from spreadsheets in Google to YouTrack.

A setup wizard navigates you through the import configuration process. It prompts you to enter the link to the Google spreadsheet and the Google API key and lets you map projects in YouTrack to sheets in the Google spreadsheet.

This option also lets you import data from a CSV or an XLSX file with a Google spreadsheet acting as an intermediary. Import your CSV or XLSX file to a Google spreadsheet first, and then import your data to YouTrack.

Import Details

If the spreadsheet contains references to entities that do not yet exist in YouTrack, they are created.

The YouTrack user account you use to run the import should have enough permissions to create all imported entities. We recommend using an account with a System Admin role or the Low-level Admin Write permission to run the import.

Imported Entities

YouTrack creates an issue for each row in the spreadsheet.
Columns are processed as custom fields and their values. For more details on processing custom fields, see Importing Custom Fields.
Values in columns with the type set to user are processed as users. YouTrack finds an existing user account or creates a new one for each user value. For details on setting a column type, see Custom field types.

Importing Custom Fields

YouTrack processes each column as a custom field or an issue attribute. The header of the column is recognized as the field name.

Here is the list of rules that YouTrack follows when importing custom fields:

If a column contains numeric data, YouTrack imports it into values of a float custom field.
If a column contains data that can be converted into dates, YouTrack imports it into values of a date and time custom field. For more details about processing date values, see Dates.
YouTrack recognizes explicitly set custom field types. You can set the field type for a column by adding the type to the column name in brackets. For field type mapping between the spreadsheet and YouTrack, see Custom Field Mapping.
When you import a column with its type explicitly set to user (for example, a column named Assignee (user)), YouTrack finds an existing user account or creates a new one for each value. New user accounts that exceed the license number are banned.
YouTrack doesn't import any data from columns with names matching standard issue attributes like created or author. For the full list of reserved field names, see Columns with names matching standard YouTrack issue attributes.
When YouTrack doesn't associate data from a column with any data type, it imports that column as a string custom field.

For details on how to prepare the data in your spreadsheet for the import, see Format the Data.

Custom Field Mapping

You can set the field type for a column by adding the type to the column name in brackets.

Currently, the import supports only a subset of custom field types available in YouTrack. This means that in some cases, even if you set a particular field type for a column, YouTrack will convert data from this column into another data type.

Here is the mapping for custom field types between the spreadsheet and YouTrack:

Spreadsheet field type	YouTrack field type	Details
`string`	`string`
`text`	`string`
`float`	`float`
`integer`	`float`
`state`	`state`
`enum`	`enum`
`version`	`enum`
`enum multi`	`enum (multi)`	YouTrack imports this field as multi-value enum-type field.
`build`	`enum (multi)`	Build-type fields are imported as multi-value `enum` custom fields.
`ownedField`	`string`	The import doesn't support `ownedField` field type yet.
`user`	`user`
`group`	`string`	The import doesn't support `group` field type yet.
`date and time`	`date and time`
`date`	`date and time`
`period`	`period`

When YouTrack doesn't associate data from a column with any data type, it imports that column as a string custom field.

Spreadsheet Setup

Before setting up import in YouTrack, you need to configure the sharing settings of your spreadsheet and preformat the data.

Make sure your Google spreadsheet is shared publicly. Otherwise, YouTrack will not be able to access the data and the import won't start.

In the sharing settings of your spreadsheet, select the Anyone with the link option and set the level of access to Viewer or higher.

Sharing settings for a Google spreadsheet

Format the Data

To make sure that YouTrack handles the data from your spreadsheet accurately, preformat the column names and the values as follows.

Summary (required)

Each imported sheet must contain a column named Summary. Data from the Summary column is converted into issue summaries.

Description

Add a column named Description to import data from this column into issue descriptions.

Dates

To import data values, make sure that these values match one of the supported date formats.

The default import script supports the following date formats:

dd.MM.yy
dd.MM.yy HH:mm
dd.MM.yyyy HH.mm
dd/MMM/yy
dd/MMM/yy HH:mm
dd MMM yyyy
yyyy-MM-dd
yyyy-MM-dd HH:mm
yyyy-MM-ddTHH:mmX
yyyy-MM-ddTHH:mm:ssX
yyyy-MM-ddTHH:mm:ss.SSSX

To customize the list of recognized date formats, edit the import script.

Columns with names matching standard YouTrack issue attributes

If your spreadsheet has columns with names matching those of standard issue attributes in YouTrack, data from these columns will not be imported. If you need to import these columns, edit their names so that they do not match any of the standard issue attributes.

Here is the list of the names reserved for the standard issue attributes:

tags
links
attachments
comments
watchers
created
updated
author
voters

The name parser is case-insensitive.

Custom field types

Define the field type for a column explicitly by adding the type to the column name in brackets. This will ensure that YouTrack creates a custom field with the right type during the import. Example: State (state).

When YouTrack doesn't associate data from a column with any data type, it imports that column as a string custom field.

For the full list of field types supported by the import, see Custom Field Mapping.

For details on how YouTrack import processes columns into custom fields, see Importing Custom Fields.

Here is an example of a spreadsheet with columns prepared for the import:

An example of a Google spreadsheet prepared for import

Set up an Import from Google Sheets

Before you add a new import configuration, you need to create an API key associated with a project in Google. After that, you'll be able to set up an import in YouTrack.

Create an API Key in Google

Due to Google policies, the YouTrack import script can only use the Google API if the requests are linked to a project in Google. To set up an import of data from Google Sheets, you need to create an API key associated with your Google account and a project in Google.

To create an API key in Google:

Open Google Cloud Console.
Log in using your Google account.
Create a new project or select an existing one.
From the Navigation menu on the left, select APIs and services > Enabled APIs and services.
Click Enable APIs and services, find the Google Sheets API, and enable it for your project.
Go back to the Enabled APIs and services page.
Click Enable APIs and services, find the Google Drive API, and enable it for your project.
From the Credentials section, click Create credentials and select API key.
- You have created an API key associated with your Google account and a project in Google.
Copy the API key to enter it in the import setup wizard.

For more information on API keys in Google, refer to the Google documentation.

Configure an Import from Google Sheets in YouTrack

The setup wizard guides you through the setup process.

To configure an import from Google Sheets:

From the Administration menu, select Integrations > Imports.
Click New import to open the setup dialog.
Select Google Sheets.

Configure the import settings:

Setting	Description
Spreadsheet URL	The public link of the spreadsheet in Google Sheets. Configure the sharing settings for the spreadsheet to allow anyone with the link to view the file.
API key	The API key that you have generated in your Google account to access the target spreadsheet.

When done, click Next.

Review the settings that you have provided.
Select the sheets and the target YouTrack projects for the import. For more details about the project mapping configuration, see Project Mapping.
When done, click Start import.
- YouTrack will create a project of the same name as the target sheet in the Google spreadsheet and import issues, custom fields, and users.
  If you have configured a project mapping, YouTrack will create new projects and import data to the existing ones according to the mapping.

When you have set up an import, it appears in the imports list. To view configuration and import details, select the import configuration from the list.

In the details sidebar, YouTrack shows import status and details on the data that was imported. Click the Resume button in the toolbar to explicitly start polling for changes and importing updates from the selected sheets in the Google spreadsheet.

You can also download the import log file to study and investigate when needed.

Project Mapping

On the final step of the import setup, you can select those sheets in the Google spreadsheet that you want to import to YouTrack. You can also choose whether to create a new project for the import or import data into an existing project in YouTrack.

To configure project mapping:

Locate those sheets that you want to import.
Use the filter bar on the right to filter the sheets by name.
Select the sheets that you want to import. Check the box on the top of the list to import all available sheets.
Select a target YouTrack project for each sheet.
- When loading the list of sheets for mapping, YouTrack checks for existing YouTrack projects with corresponding names. If it finds a YouTrack project with the same name as the sheet in the Google spreadsheet, YouTrack suggests it as the target project.
- If there is no existing YouTrack project with the corresponding name, YouTrack suggests creating a new one.
If you want to change a target project, select another option from the corresponding dropdown on the list.
Click Next to start import.
- Import starts.

Import Options

After the initial import, the following controls are available in the sidebar:

Control	Description
Resume	Immediately imports any changes made in the selected sheets in the Google spreadsheet after the previous import.
Edit	Opens the integration settings page in edit mode. Use this option to connect to a different Google spreadsheet, update the API key, or update project mapping.
Delete	Deletes the current import settings. Projects and issues that were imported from the connected Google spreadsheet are not affected. If you delete the import settings and connect to the same Google Sheets spreadsheet, the issues are re-imported into existing projects with new issue IDs.
Download import log	Downloads the import log. Use this option to view and investigate errors that occurred during import.

Last modified: 13 October 2022