---
schema: rendered-html/v1
title: "Working with Import Scripts | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/working-with-import-scripts.html
generated_at: 2026-06-11T15:21:12.717978+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- Get Started with Import Scripts
- How Import Scripts Work
- Imported Entities
- [Working with Import Scripts](working-with-import-scripts.html)
- Demo Import Script
- Connect to an External Tool
- YouTrack Import API
- YouTrack Form API
- [YouTrack REST API](jetbrains__com__help__youtrack__devportal__youtrack-rest-api.md)
- Hub REST API

1. YouTrack Import Scripts
2. Get Started with Import Scripts
3. [Working with Import Scripts](#0)

# Working with Import Scripts﻿

Last modified: 07 May 2026

This article helps you work with the import scripts in YouTrack. Here you'll learn how to create an import script, edit a script, set up an import configuration and run an import.

## Create an Import Script﻿

### To create an import script:﻿

> ### tip
>
> Requires permission: Low-level Admin Write

1. From the Administration menu, select Integrations > Imports.
2. Click the New import button to open the setup dialog.

   [![New import dialog](https://crawler.prototype.prolicht.digital/l/KzPDPN)](https://resources.jetbrains.com/help/img/youtrack/custom-import-new-select.png)
3. Select Custom import.
4. Expand the Import script package dropdown menu.

   [![Create new import script package](https://crawler.prototype.prolicht.digital/l/sxTDga)](https://resources.jetbrains.com/help/img/youtrack/create-new-import-script-package.png)
5. Select New import script package.

   - The New Import Script Package dialog opens.[![Enter new import script name and title](https://crawler.prototype.prolicht.digital/l/PGY8WJ)](https://resources.jetbrains.com/help/img/youtrack/new-custom-import-name.png)
6. Enter a Name and a Title.
7. Click the Create button.

   - A new script package is created in the background. This new script is then selected in the Import script package dropdown menu.
   - The script package you've just created includes one file named `client.js`, which contains a template for an import script.

Now that you have a template of an import script, you'll need to customize it for your needs.

## Edit an Import Script﻿

When you have a template for an import script, you can edit it in the web-based script editor.

### To edit an import script:﻿

1. From the Administration menu, select Integrations > Imports.
2. Click the New import button to open the setup dialog.
3. If you want to edit a custom import script, select Custom import. If you want to edit the script for one of the predefined imports, select the option for that import.
4. If you've selected the Custom import option, select the script you've created in the Import script package dropdown menu.
5. Click the customize the import script link at the bottom of the dialog.

   [![Customize the import script](https://crawler.prototype.prolicht.digital/l/uXSkmS)](https://resources.jetbrains.com/help/img/youtrack/customize-new-import.png)
   - A new browser tab with the web-based script editor opens.
   - The target import script is selected in the editor sidebar.

> ### tip
>
> If you've already set up an import configuration, you can edit the script for it directly from the Administration > Integrations > Imports page. To do that, select the import configuration, click the Edit button in the import details panel, and click the customize the import script link at the bottom of the panel.

Now that you have opened the import script in the editor, you can customize it.

To learn about working in the web-based script editor, see Web-based Workflow Editor.

## Set up an Import﻿

When you have edited and saved the import script package, return to the Import page and follow the setup wizard for the relevant import type.

If you have changed the script for a predefined import, select the option for that import source. If you have created a custom import script, select the Custom Import option.

Follow the setup wizard, enter the connection details, and configure the project mapping. When done, click Start import.

- YouTrack will create a project of the same name as the target project in the import source and import entities according to the corresponding import script.

  If you have configured a project mapping, YouTrack will create new projects and import data to the existing ones according to the mapping.
- If the Continuous import option is enabled, YouTrack will periodically check the import source for updates.

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. After the initial import, the following controls are available in the sidebar:

| Control | Description |
| --- | --- |
| Resume | Immediately imports any changes that were made in the selected projects in the import source after the previous import. |
| Edit | Opens the integration settings page in edit mode. Use this option to change the connection details, update the login credentials, update the project mapping, or edit the import script. |
| Delete | Deletes the current import settings. Projects, issues, users, and groups that were imported from the connected import source are not affected. If you delete the import settings and connect to the same import source, the issues are re-imported into existing projects with new issue IDs. |

## Troubleshooting﻿

If the import doesn't work as expected, you have several options to troubleshoot the problems you face.

| Option | Description |
| --- | --- |
| Import log | After the initial import, you can download the import log in the import details panel. The log contains all the relevant information about the import process and the imported entities. |
| The console of the web-based editor | To understand better what is happening at a particular stage of an import, you can add console messages to your script. Use the `console.log()` method for adding console messages. To learn how to work with the console in the web-based editor, see Web-based Workflow Editor. |

- [Working with Import Scripts](/help/youtrack/devportal/working-with-import-scripts.html)
- [Create an Import Script](/help/youtrack/devportal/working-with-import-scripts.html#create-import-script)
- [Edit an Import Script](/help/youtrack/devportal/working-with-import-scripts.html#edit-import-script)
- [Set up an Import](/help/youtrack/devportal/working-with-import-scripts.html#set-up-import)
- [Troubleshooting](/help/youtrack/devportal/working-with-import-scripts.html#troubleshooting)

Imported EntitiesDemo Import Script

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
