How Import Scripts Work

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:

   • Checks that all required fields have values and correct types.

   • Checks that each field uses the same representation (strings or objects) and has the same type in each issue.

   • Searches for users and groups mentioned in each issue (authors, updaters, field values) and creates respective users and groups in YouTrack and Hub.

   • Retrieves members of each user group mentioned in each issue via getUsers function and creates each user in YouTrack and Hub.

   • Defines types for fields that use string representation. If the field already exists in YouTrack, its type is preserved.

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