Working with Import Scripts - Help | Developer Portal for YouTrack and Hub

Create an Import Script

To create an import script:

From the Administration menu, select Integrations > Imports.
Click the New import button to open the setup dialog.
Select Custom import.
Expand the Import script package dropdown menu.
Select New import script package.
- The New Import Script Package dialog opens.
Enter a Name and a Title.
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:

From the Administration menu, select Integrations > Imports.
Click the New import button to open the setup dialog.
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.
If you've selected the Custom import option, select the script you've created in the Import script package dropdown menu.
Click the customize the import script link at the bottom of the dialog.
- A new browser tab with the web-based script editor opens.
- The target import script is selected in the editor sidebar.

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.