Custom Imports
To import data to YouTrack from an external source, you can customize one of the import scripts that are built in YouTrack as well as create a new import script from scratch.
Custom import scripts are written in JavaScript using JSON as an intermediary data scheme. All data that is imported into YouTrack is converted into JSON and then into YouTrack entities.
Set up a New Custom Import
To import data to YouTrack from an external source, you need to create a new custom import script package.
To create a new import script:
From the Administration menu, select .
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 import script is created in the background. This new script is then selected in the Import script package dropdown menu.
Now you have a new import script package, but it needs to be configured to convert all the data that you need from the external source to YouTrack entities.
To open the script that you’ve just created in the web-based script editor, click the customize the import script link at the bottom of the dialog. To learn how to write and customize import scripts, examine the demo import script and consult the custom import API reference. Once you’ve finished editing the script, proceed with the import configuration.
To learn about working in the web-based script editor, see Web-based Workflow Editor.
To configure a custom import:
From the Administration menu, select .
Click the New import button to open the setup dialog.
Select Custom import.
The New Custom Import dialog opens.
Enter values for the following settings:
Setting Description URL Enter the URL of the import source. Username or email Enter the username or email for the user account in the import source with the access to the data that you need to import. Password or token Enter the password or token that is used to authenticate the user in the import source. Import script package Select the import script you've created. Click the Next button to open the next part of the configuration dialog.
In the dropdown, select the projects that you need to import data from. To import data from all projects in the import source, leave the default All projects setting.
If the custom import source supports continuous import mode, activate the Continuous import switch.
Click the Start import button.
Entities that are covered by the custom import script logic are imported to YouTrack.
If the Continuous import option is enabled, YouTrack will periodically check the import source for updates.
The Download import link option lets you download the import log. Use this option to view and investigate errors that occurred during import.
Examine the Demo Import Script
To get an idea of how a custom import script works, have a look at the predefined demo import script that is built in to your YouTrack.
To open the demo import script package:
From the Administration menu, select .
Click the New import button to open the setup dialog.
Select Custom import.
The New Custom Import dialog opens.
Make sure that in the Import script package dropdown menu, the default
@jetbrains/youtrack-demo-clientscript is selected.
Click the customize import script link at the bottom of the page.
The web-based script editor opens with the demo script package expanded. To learn about working in the web-based script editor, see Web-based Workflow Editor.
The demo script package consists of five files. The main script file is named client.js. It contains the import logic and the API reference. Consult this file as an example script.
The other four files contain hard-coded demo data in JSON format. This data is then converted into YouTrack entities when the demo import script is run.
These four files show you what attributes can be imported for issues, articles, projects, and users. Consult these files to learn which data format is expected from the import source.
Customize a Predefined Import Script
To import entities that are not covered by the logic in the predefined imports from GitHub, Jira, MantisBT, Redmine, Bugzilla, YouTrack, and Confluence, you may edit the corresponding script.
To open a predefined script package in the web-based editor:
From the Administration menu, select .
Click the New import button to open the setup dialog.
Select the option corresponding to your import source.
Click the customize import script link at the bottom of the page.
The web-based script editor opens with the relevant script package expanded. To learn about working in the web-based script editor, see Web-based Workflow Editor.
Now you may make changes to the predefined import script. Consult the API reference for more information.
Imported Entities
The API for imports supports many types of entities that you can import from the external source to YouTrack. However, there are entities that are not covered and can't be imported using this method. It's possible to import some of these entities using the YouTrack REST API and the Hub REST API.
The following entities can be imported into YouTrack with import scripts:
Projects
Issues
Custom fields and their values
Comments
Attachments
Work items
Links
Tags
Articles
Users
Groups
The following entities can't be imported into YouTrack with import scripts:
Agile boards. To import these entities, use the YouTrack REST API.
Reports
Dashboards. To import these entities, use the Hub REST API.