YouTrack Server 2022.3 Help

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:

  1. From the Administration menu, select Integrations > Imports.

  2. Click the New import button to open the setup dialog.

    New import dialog
  3. Select Custom import.

  4. Expand the Import script package dropdown menu.

    Create new import script package
  5. Select New import script package.

    • The New Import Script Package dialog opens.

    Enter new import script name and title
  6. Enter a Name and a Title.

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

  1. From the Administration menu, select Integrations > Imports.

  2. Click the New import button to open the setup dialog.

    New import dialog
  3. Select Custom import.

    • The New Custom Import dialog opens.

  4. Enter values for the following settings:

    Custom import 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.

  5. Click the Next button to open the next part of the configuration dialog.

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

    New custom import step two
  7. If the custom import source supports continuous import mode, activate the Continuous import switch.

  8. Click the Start import button.

    Custom import results
    • 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:

  1. From the Administration menu, select Integrations > Imports.

  2. Click the New import button to open the setup dialog.

    New import dialog
  3. Select Custom import.

    • The New Custom Import dialog opens.

  4. Make sure that in the Import script package dropdown menu, the default @jetbrains/youtrack-demo-client script is selected.

    Select demo client
  5. 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.

Data for the demo client

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, GitLab, Zendesk, monday.com, YouTrack, and Confluence, you may edit the corresponding script.

To open a predefined script package in the web-based editor:

  1. From the Administration menu, select Integrations > Imports.

  2. Click the New import button to open the setup dialog.

  3. Select the option corresponding to your import source.

  4. Click the customize import script link at the bottom of the page.

    Customize a predefined import script
    • 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:

Last modified: 02 August 2022