---
schema: rendered-html/v1
title: "How Import Scripts Work | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/how-import-scripts-work.html
generated_at: 2026-06-11T15:02:53.674527+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](jetbrains__com__help__youtrack__devportal__get-started-custom-import-scripts.md)
- [How Import Scripts Work](how-import-scripts-work.html)
- [Imported Entities](jetbrains__com__help__youtrack__devportal__imported-entities.md)
- Working with Import Scripts
- [Demo Import Script](jetbrains__com__help__youtrack__devportal__demo-import-script.md)
- Connect to an External Tool
- YouTrack Import API
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. YouTrack Import Scripts
2. [Get Started with Import Scripts](jetbrains__com__help__youtrack__devportal__get-started-custom-import-scripts.md)
3. [How Import Scripts Work](#0)

# How Import Scripts Work﻿

Last modified: 07 May 2026

In this article, we describe how import scripts work. You'll learn how import scripts receive and handle data, and how data from an external tool transforms into YouTrack data.

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.

When importing data from an external source, YouTrack does the following:

1. Establishes connection between YouTrack and the import source. In the demo client, this part is not implemented as the demo client uses a predefined hard-coded set of data.
2. Calls the `prepareToImport` function. In this function, the client can perform any necessary initialization.
3. Via the `getProjects` function, requests projects from the import source.
4. Searches for users and groups mentioned in each project (project leaders, teams, subsystem owners) and creates respective users and groups in YouTrack and Hub.
5. When creating a group, retrieves its members via the `getUsers` function and creates each user in YouTrack and Hub.
6. For each project, creates custom field prototypes in case the retrieved project contains descriptions of project fields.
7. For each project, requests issues in chunks via the `getIssues` function.
8. For each chunk of issues:

   1. Checks that all required fields have values and correct types.
   2. Checks that each field uses the same representation (strings or objects) and has the same type in each issue.
   3. Searches for users and groups mentioned in each issue (authors, updaters, field values) and creates respective users and groups in YouTrack and Hub.
   4. Retrieves members of each user group mentioned in each issue via `getUsers` function and creates each user in YouTrack and Hub.
   5. Defines types for fields that use string representation. If the field already exists in YouTrack, its type is preserved.
   6. If the field does not exist in YouTrack yet, creates this field with the `string` type. Creates values to be assigned to YouTrack issue fields.
9. For each issue from the import source, creates a YouTrack issue and assigns values to its fields.

[Get Started with Import Scripts](jetbrains__com__help__youtrack__devportal__get-started-custom-import-scripts.md)[Imported Entities](jetbrains__com__help__youtrack__devportal__imported-entities.md)

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

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

![](https://bat.bing.com/action/0?ti=5220035&tm=gtm002&Ver=2&mid=d9339c14-181a-4378-ba8c-15736efa4994&bo=4&sid=452929b065a111f19a7fe7356f74a419&vid=aa3122f0648711f1a10d6d095e10fd87&vids=0&msclkid=N&pi=918639831&lg=en-US&sw=1920&sh=1080&sc=24&tl=How%20Import%20Scripts%20Work%20%7C%20Developer%20Portal%20for%20YouTrack%20and%20Hub%20Documentation&p=https%3A%2F%2Fwww.jetbrains.com%2Fhelp%2Fyoutrack%2Fdevportal%2Fhow-import-scripts-work.html&r=&lt=659&pt=1781190171157,33,33,,,1,1,1,1,1,,2,29,30,36,237,237,237,658,659,659&pn=0,0&evt=pageLoad&sv=2&asc=G&cdb=AQAS&rn=486677)
